@atlaskit/top-layer 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @atlaskit/top-layer
 
+## 0.15.0
+
+### Minor Changes
+
+- [`e5b4070f51a93`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/e5b4070f51a93) -
+  Remove Top Layer compatibility aliases and expose close-event helpers from the `dialog` and
+  `popover` entry points.
+
+## 0.14.0
+
+### Minor Changes
+
+- [`021a645c6f39a`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/021a645c6f39a) -
+  Remove the `Popup` compound and `PopupSurface`; use `Popover`, `PopoverSurface`,
+  `useAnchorPosition`, `useWidthFromAnchor`, `usePopoverId`, and `getAriaForTrigger` instead.
+
+  Nested-popover focus restoration is now automatic: `Popover` snapshots `document.activeElement` in
+  `beforetoggle` (newState='open') and restores it on close for focus-capturing roles (`dialog`,
+  `alertdialog`, `menu`, `listbox`, `tree`, `grid`) when the close reason is Escape or programmatic.
+  Click-outside (light dismiss) intentionally does not restore focus, matching the HTML Popover
+  spec's `focusPreviousElement=false` rule. This fixes a Firefox bug where nested popovers left
+  focus on `<body>` after dismiss.
+
 ## 0.13.0
 
 ### Minor Changes

package/README.md

@@ -4,36 +4,63 @@ Low-level top-layer primitives using the native
 [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) (`popover="auto"`) and
 [`<dialog>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog) element.
 
-## Popup
+## Popover
 
-Compound component for rendering content in the browser's top layer with CSS Anchor Positioning.
-Placement is owned by this compound: root provides it via context, Content applies it (CSS Anchor
-Positioning or JS fallback).
+The primary primitive: a `<div>` with the `popover` attribute, plus a small lifecycle (animations,
+role-based focus management, light-dismiss, nested-focus restoration). It does **not** know about
+placement — compose it with the `useAnchorPosition` hook when you need anchor-positioned content.
 
 ```tsx
-<Popup onClose={handleClose}>
-	<Popup.Trigger>
-		<button>Open</button>
-	</Popup.Trigger>
-	<Popup.Content role="dialog" label="My popup">
-		Content here
-	</Popup.Content>
-</Popup>
+import { useRef } from 'react';
+import { slideAndFade } from '@atlaskit/top-layer/animations';
+import { getAriaForTrigger } from '@atlaskit/top-layer/get-aria-for-trigger';
+import { Popover } from '@atlaskit/top-layer/popover';
+import { PopoverSurface } from '@atlaskit/top-layer/popover-surface';
+import { usePopoverId } from '@atlaskit/top-layer/use-popover-id';
+import { useAnchorPosition } from '@atlaskit/top-layer/use-anchor-position';
+
+function MyPopup({ isOpen, onClose }: { isOpen: boolean; onClose: () => void }) {
+	const triggerRef = useRef<HTMLButtonElement>(null);
+	const popoverRef = useRef<HTMLDivElement>(null);
+	const popoverId = usePopoverId();
+
+	useAnchorPosition({
+		anchorRef: triggerRef,
+		popoverRef,
+		placement: { axis: 'block', edge: 'end', align: 'start' },
+	});
+
+	return (
+		<>
+			<button
+				ref={triggerRef}
+				onClick={() => popoverRef.current?.togglePopover()}
+				{...getAriaForTrigger({ role: 'dialog', isOpen, popoverId })}
+			>
+				Open
+			</button>
+			<Popover
+				ref={popoverRef}
+				id={popoverId}
+				role="dialog"
+				label="Settings"
+				isOpen={isOpen}
+				animate={slideAndFade()}
+				onClose={onClose}
+			>
+				<PopoverSurface>Content here</PopoverSurface>
+			</Popover>
+		</>
+	);
+}
 ```
 
-`placement` defaults to `{}` - "below trigger, centered, with `space.100` gap". Pass an explicit
-object to override (e.g. `placement={{ axis: 'inline', edge: 'end' }}` for a popover anchored to the
-trigger's right edge).
-
-For default overlay styling (background, shadow, border-radius), see `PopupSurface` in the package
-examples (not currently a public API; we may expose it in a future release).
-
-## Popover
-
-Low-level primitive: a `<div>` with the `popover` attribute and show/hide lifecycle only. No
-placement, no trigger wiring — use it when you need top-layer rendering with **fixed or custom
-positioning** (e.g. Flag uses `Popover mode="manual"`). For anchor-positioned content next to a
-trigger, use **Popup** instead.
+- Focus restoration is automatic. The browser handles it for outermost popovers; `Popover`
+  snapshots `document.activeElement` on open and restores it on close for nested cases.
+- For default overlay styling (background, shadow, border-radius), wrap content in `PopoverSurface`
+  from `@atlaskit/top-layer/popover-surface`.
+- For trigger-less or custom-positioned UI (flag, tooltip, react-select menu portal), use `Popover`
+  on its own without `useAnchorPosition`.
 
 ## Dialog
 
@@ -60,8 +87,8 @@ Compound component for modal dialogs using the native `<dialog>` element with `.
 
 ## Animations
 
-Both Popup (and the low-level Popover) and Dialog support CSS-based entry/exit animations via the
-`animate` prop. Animations use
+Both `Popover` and `Dialog` support CSS-based entry/exit animations via the `animate` prop.
+Animations use
 [`@starting-style`](https://developer.mozilla.org/en-US/docs/Web/CSS/@starting-style) for entry and
 [`allow-discrete`](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-behavior) on
 `display`/`overlay` for exit — no JavaScript animation coordination required.
@@ -80,23 +107,23 @@ import {
 } from '@atlaskit/top-layer/animations';
 ```
 
-### Popup animation
+### Popover animation
 
-Pass a preset to `Popup.Content` (or to `Popover` when using the low-level primitive without
-placement):
+Pass a preset to `Popover`:
 
 ```tsx
 import { slideAndFade } from '@atlaskit/top-layer/animations';
+import { Popover } from '@atlaskit/top-layer/popover';
 
 const animation = slideAndFade();
 
-<Popup.Content animate={animation} role="dialog" label="My popup">
+<Popover animate={animation} role="dialog" label="My popover">
 	Content
-</Popup.Content>;
+</Popover>;
 ```
 
-For overlay styling (background, shadow, border-radius), see the `PopupSurface` usage in the package
-examples.
+For overlay styling (background, shadow, border-radius), wrap children in `PopoverSurface` from
+`@atlaskit/top-layer/popover-surface`.
 
 Available popover presets:
 

package/dist/cjs/animations/presets.js

@@ -67,10 +67,10 @@ var SLIDE_AND_FADE_CSS = "\n[data-ds-popover-slide-and-fade] {\n  opacity: 0;\n
  * import { slideAndFade } from '@atlaskit/top-layer/animations';
  *
  * // Default 4px slide (tooltip)
- * <Popup.Content animate={slideAndFade()} />
+ * <Popover animate={slideAndFade()} />
  *
  * // Custom 8px slide (popup / dropdown)
- * <Popup.Content animate={slideAndFade({ distance: 8 })} />
+ * <Popover animate={slideAndFade({ distance: 8 })} />
  * ```
  */
 function slideAndFade(options) {
@@ -104,7 +104,7 @@ var FADE_CSS = "\n[data-ds-popover-fade] {\n  opacity: 0;\n  transition:\n    op
  * ```tsx
  * import { fade } from '@atlaskit/top-layer/animations';
  *
- * <Popup.Content animate={fade()} />
+ * <Popover animate={fade()} />
  * ```
  */
 // eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
@@ -130,7 +130,7 @@ var SCALE_AND_FADE_CSS = "\n[data-ds-popover-scale-and-fade] {\n  opacity: 0;\n
  * ```tsx
  * import { scaleAndFade } from '@atlaskit/top-layer/animations';
  *
- * <Popup.Content animate={scaleAndFade()} />
+ * <Popover animate={scaleAndFade()} />
  * ```
  */
 // eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports

package/dist/cjs/dialog/create-close-event.js

@@ -16,8 +16,7 @@ exports.createCloseEvent = createCloseEvent;
  *
  * @example
  * ```tsx
- * import { createCloseEvent } from '@atlaskit/top-layer/create-close-event';
- * import { type TDialogCloseReason } from '@atlaskit/top-layer/dialog';
+ * import { createCloseEvent, type TDialogCloseReason } from '@atlaskit/top-layer/dialog';
  *
  * function onDialogClose({ reason }: { reason: TDialogCloseReason }) {
  *   legacyOnClose(createCloseEvent({ reason }));

package/dist/cjs/entry-points/dialog.js

@@ -9,4 +9,10 @@ Object.defineProperty(exports, "Dialog", {
     return _dialog.Dialog;
   }
 });
+Object.defineProperty(exports, "createCloseEvent", {
+  enumerable: true,
+  get: function get() {
+    return _dialog.createCloseEvent;
+  }
+});
 var _dialog = require("../dialog");

package/dist/cjs/entry-points/get-aria-for-trigger.js

@@ -0,0 +1,12 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "getAriaForTrigger", {
+  enumerable: true,
+  get: function get() {
+    return _getAriaForTrigger.getAriaForTrigger;
+  }
+});
+var _getAriaForTrigger = require("../internal/get-aria-for-trigger");

package/dist/cjs/entry-points/popover-surface.js

@@ -0,0 +1,12 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "PopoverSurface", {
+  enumerable: true,
+  get: function get() {
+    return _popoverSurface.PopoverSurface;
+  }
+});
+var _popoverSurface = require("../popover-surface");

package/dist/cjs/entry-points/popover.js

@@ -9,4 +9,10 @@ Object.defineProperty(exports, "Popover", {
     return _popover.Popover;
   }
 });
+Object.defineProperty(exports, "createPopoverCloseEvent", {
+  enumerable: true,
+  get: function get() {
+    return _popover.createPopoverCloseEvent;
+  }
+});
 var _popover = require("../popover");

package/dist/cjs/entry-points/use-popover-id.js

@@ -0,0 +1,21 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.usePopoverId = usePopoverId;
+var _useId = require("@atlaskit/ds-lib/use-id");
+/**
+ * Returns a stable HTML `id` used to wire a trigger element to its popover
+ * via ARIA (`aria-controls`) and the Popover API (`popovertarget`).
+ *
+ * The returned value is intended for the `id` attribute on the popover and
+ * for the matching `aria-controls` / `popovertarget` references on the
+ * trigger. It is NOT a CSS `anchor-name` value: CSS anchor positioning is
+ * handled internally by `useAnchorPosition`, which mints and applies its
+ * own `anchor-name` on the trigger element.
+ */
+function usePopoverId() {
+  // prefixing for debug clarity in the DOM
+  return "popover-".concat((0, _useId.useId)());
+}

package/dist/cjs/internal/get-aria-for-trigger.js

@@ -0,0 +1,88 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getAriaForTrigger = getAriaForTrigger;
+var _roleToAriaHasPopup = require("./role-to-aria-has-popup");
+/**
+ * Roles accepted by `getAriaForTrigger`.
+ *
+ * Excludes tooltip-family roles (`tooltip`, `note`, `status`, `alert`, `log`)
+ * because the correct trigger wiring for those is `aria-describedby`, not
+ * `aria-haspopup` / `aria-expanded` / `aria-controls`. Use `aria-describedby`
+ * manually for tooltip triggers.
+ */
+
+/**
+ * Non-undefined subset of `TAriaHasPopupValue`. Every role accepted by
+ * `getAriaForTrigger` maps to a concrete `aria-haspopup` string, so the
+ * trigger always receives a defined attribute value.
+ */
+
+/**
+ * Returns the ARIA attributes to spread onto a click-activated popover trigger.
+ *
+ * Centralises three attributes that are easy to forget or get wrong individually:
+ *
+ * - `aria-haspopup` - derived from the popover's role (e.g. `dialog → "dialog"`,
+ *   `menu → "menu"`, `tooltip → undefined`). React omits the attribute when
+ *   the value is `undefined`.
+ * - `aria-expanded` - reflects the current open state.
+ * - `aria-controls` - references the popover element by its id, even
+ *   while the popover is closed. The relationship is stable; `aria-expanded`
+ *   carries the current visibility state.
+ *
+ * **This function is for click/keyboard-activated popovers only.** For
+ * hover-driven tooltips, the trigger should use `aria-describedby` instead.
+ *
+ * @example
+ * ```tsx
+ * import { getAriaForTrigger } from '@atlaskit/top-layer/get-aria-for-trigger';
+ * import { usePopoverId } from '@atlaskit/top-layer/use-popover-id';
+ *
+ * const popoverId = usePopoverId();
+ * const [isOpen, setIsOpen] = useState(false);
+ *
+ * return (
+ *   <>
+ *     <button
+ *       ref={triggerRef}
+ *       onClick={() => setIsOpen((previous) => !previous)}
+ *       {...getAriaForTrigger({ role: 'dialog', isOpen, popoverId })}
+ *     >
+ *       Open
+ *     </button>
+ *     <Popover
+ *       id={popoverId}
+ *       role="dialog"
+ *       label="My dialog"
+ *       isOpen={isOpen}
+ *       triggerRef={triggerRef}
+ *       onClose={() => setIsOpen(false)}
+ *     >
+ *       …
+ *     </Popover>
+ *   </>
+ * );
+ * ```
+ */
+function getAriaForTrigger(_ref) {
+  var role = _ref.role,
+    isOpen = _ref.isOpen,
+    popoverId = _ref.popoverId;
+  // `roleToAriaHasPopup` accepts a wider role union (including tooltip-family
+  // roles that map to `undefined`). `TAriaForTriggerRole` excludes those, so
+  // the returned value is guaranteed to be a defined string. The cast narrows
+  // the wider helper signature to match.
+  var ariaHasPopup = (0, _roleToAriaHasPopup.roleToAriaHasPopup)({
+    role: role
+  });
+  return {
+    'aria-haspopup': ariaHasPopup,
+    'aria-expanded': isOpen,
+    // Keep the trigger-to-popover relationship stable. `aria-expanded`
+    // tells assistive technology whether the controlled popover is visible.
+    'aria-controls': popoverId
+  };
+}

package/dist/cjs/internal/role-types.js

@@ -1 +1,64 @@
-"use strict";
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.shouldFocusIntoPopover = shouldFocusIntoPopover;
+/**
+ * Valid values for the `aria-haspopup` attribute.
+ *
+ * Derived from the HTML spec - maps popover roles to what the trigger
+ * announces. `undefined` means the attribute is omitted entirely (used for
+ * non-popup roles like `tooltip`/`status`/`alert`/`note`/`log` where
+ * `aria-haspopup` would be misleading).
+ *
+ * `true` is intentionally NOT in the union - the runtime only ever produces
+ * the explicit string forms, so widening the type would invite consumers to
+ * pass `true` and get an `aria-haspopup="true"` serialisation that the
+ * runtime no longer emits.
+ */
+
+/**
+ * Roles that require an accessible name (`label` or `labelledBy`) per WCAG 4.1.2.
+ * Without a name, assistive technology cannot identify these landmarks.
+ */
+
+/**
+ * Roles where the accessible name is derived from content or provided externally
+ * (e.g. a combobox labels its listbox, tooltip content IS the accessible name).
+ */
+
+// Shared ARIA role discrimination types
+//
+// These encode the WCAG 4.1.2 constraint: roles like `dialog`, `alertdialog`,
+// and `menu` MUST have an accessible name (either `label` or `labelledBy`).
+// TypeScript enforces this at compile time via discriminated unions.
+
+/**
+ * ARIA role props where a role is always required.
+ *
+ * Used by `TPopupContentProps`. Popup content must always declare
+ * its role so assistive technology can identify the layer.
+ */
+
+/**
+ * ARIA role props where a role is optional.
+ *
+ * Used by `TPopoverProps`. The low-level primitive allows omitting
+ * the role for cases where it is set externally or not needed.
+ */
+
+var rolesThatMoveFocus = new Set(['dialog', 'alertdialog', 'menu', 'listbox', 'tree', 'grid']);
+
+/**
+ * Returns `true` when the given popover role moves focus into the popover
+ * on open, and `false` otherwise (including when `role` is `undefined`).
+ */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
+function shouldFocusIntoPopover(_ref) {
+  var role = _ref.role;
+  if (!role) {
+    return false;
+  }
+  return rolesThatMoveFocus.has(role);
+}

package/dist/cjs/internal/slot.js

@@ -52,7 +52,7 @@ function isSlotChild(child) {
 var Slot = exports.Slot = /*#__PURE__*/(0, _react.forwardRef)(function Slot(slotProps, ref) {
   var rawChildren = slotProps.children,
     props = (0, _objectWithoutProperties2.default)(slotProps, _excluded);
-  // `TSlotProps` intersects `Record<string, unknown>`, so `children` is typed as `unknown`.
+  // `SlotProps` intersects `Record<string, unknown>`, so `children` is typed as `unknown`.
   var children = rawChildren;
   if (!isSlotChild(children)) {
     return children;

package/dist/cjs/internal/use-anchor-position.js

@@ -5,6 +5,8 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.useAnchorPosition = useAnchorPosition;
+var _classCallCheck2 = _interopRequireDefault(require("@babel/runtime/helpers/classCallCheck"));
+var _createClass2 = _interopRequireDefault(require("@babel/runtime/helpers/createClass"));
 var _react = require("react");
 var _bindEventListener = require("bind-event-listener");
 var _rafSchd = _interopRequireDefault(require("raf-schd"));
@@ -35,15 +37,25 @@ var _setStyle = require("./set-style");
 // from `./resolve-placement` so search-and-jump lands at the source of truth.
 
 /**
- * Module-scope no-op `ResizeObserver` stub used in non-DOM jest environments where
+ * Module-scope no-op `ResizeObserver` used in non-DOM jest environments where
  * `ResizeObserver` is `undefined`. Hoisted out of the effect to avoid
- * re-allocating on every run.
+ * allocating a new class declaration on every run.
  */
-var noopResizeObserver = {
-  observe: function observe() {},
-  unobserve: function unobserve() {},
-  disconnect: function disconnect() {}
-};
+var NoopResizeObserver = /*#__PURE__*/function () {
+  function NoopResizeObserver() {
+    (0, _classCallCheck2.default)(this, NoopResizeObserver);
+  }
+  return (0, _createClass2.default)(NoopResizeObserver, [{
+    key: "observe",
+    value: function observe() {}
+  }, {
+    key: "unobserve",
+    value: function unobserve() {}
+  }, {
+    key: "disconnect",
+    value: function disconnect() {}
+  }]);
+}();
 
 /**
  * Returns true when the popover is currently open. Wrapped because the
@@ -200,6 +212,7 @@ function useStablePlacement(placement) {
  * comparison is used internally so re-runs are skipped when the resolved
  * placement shape is unchanged.
  */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 function useAnchorPosition(_ref3) {
   var anchorRef = _ref3.anchorRef,
     popoverRef = _ref3.popoverRef,
@@ -406,17 +419,20 @@ function useAnchorPosition(_ref3) {
     // Self-disconnects after one valid measurement; ongoing
     // scroll/resize is handled by the window listeners below.
     // `ResizeObserver` is missing in some non-DOM jest environments
-    // (e.g. post-office's `node` environment). Fall back to the
-    // module-scope `noopResizeObserver` stub there. The scroll/resize
-    // listeners below still keep the popover positioned in the rare
-    // case the consumer also polyfilled `showPopover` but not
-    // `ResizeObserver`. Real browsers always have it.
-    var resizeObserver = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(function () {
+    // (e.g. post-office's `node` environment). Fall back to a no-op
+    // observer there. The scroll/resize listeners below still keep
+    // the popover positioned in the rare case the consumer also
+    // polyfilled `showPopover` but not `ResizeObserver`. Real
+    // browsers always have it. The `NoopResizeObserver` class is
+    // hoisted to module scope (see top of file) so we do not allocate
+    // a new constructor on every effect run.
+    var ResizeObserverImpl = typeof ResizeObserver !== 'undefined' ? ResizeObserver : NoopResizeObserver;
+    var resizeObserver = new ResizeObserverImpl(function () {
       if (popover.offsetWidth > 0 && popover.offsetHeight > 0) {
         update();
         resizeObserver.disconnect();
       }
-    }) : noopResizeObserver;
+    });
 
     // If the popover is already open by the time this effect runs (for
     // example, the parent `useAnchorPosition` effect runs after the child

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

@@ -18,8 +18,7 @@ exports.createPopoverCloseEvent = createPopoverCloseEvent;
  *
  * @example
  * ```tsx
- * import { createPopoverCloseEvent } from '@atlaskit/top-layer/create-close-event';
- * import { type TPopoverCloseReason } from '@atlaskit/top-layer/popover';
+ * import { createPopoverCloseEvent, type TPopoverCloseReason } from '@atlaskit/top-layer/popover';
  *
  * function onPopoverClose({ reason }: { reason: TPopoverCloseReason }) {
  *   legacyOnClose(createPopoverCloseEvent({ reason }));