@atlaskit/top-layer 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @atlaskit/top-layer
 
+## 0.16.0
+
+### Minor Changes
+
+- [`6d0485dce81c4`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/6d0485dce81c4) -
+  `Popover` and `Dialog` now unmount their host element after the exit animation completes, instead
+  of leaving an empty `role` / `aria-*` element in the accessibility tree.
+
+  Other small changes that fall out of this:
+  - The popover/dialog `id` stays stable across opens.
+  - `ref.current` is only populated while the host element is rendered. Read the ref inside
+    `onOpenChange` / `onEnterFinish`, or gate the read on `isOpen`.
+  - `onEnterFinish` and `onExitFinish` now fire before the internal phase transition that drives the
+    unmount, so consumers reading the host element (or a forwarded ref) inside those callbacks
+    always see it attached to the DOM, regardless of React batching semantics.
+  - `getAriaForTrigger` returns `aria-controls: undefined` while `isOpen` is `false`; spreading the
+    result onto a JSX element strips the attribute from the DOM and avoids a dangling reference.
+  - `useAnchorPosition`, `useAnchorPositionAtPoint`, and `useWidthFromAnchor` now require `isOpen`
+    so positioning re-runs against the freshly mounted host element on each open.
+    `useWidthFromAnchor` also requires `anchorRef`.
+  - `DialogScrollLock` now requires an `isOpen` prop so the scroll lock is released the moment
+    `isOpen` flips to `false`, regardless of React's unmount timing.
+  - `useInitialFocus` now follows the WAI-ARIA APG Combobox Pattern: when a `menu` or `listbox`
+    popup is controlled by a focused combobox-like textbox whose `aria-controls` (or legacy
+    `aria-owns`) references the popup, initial focus stays on the textbox instead of moving into the
+    popup. Navigation is expected to be proxied via `aria-activedescendant`. Both variants are
+    detected:
+    - **In-popup combobox**: the focused textbox lives inside the popup.
+    - **External combobox**: the focused textbox is rendered OUTSIDE the popup (for example
+      `react-select`-style menus that portal the listbox). The carve-out also accepts the case where
+      the textbox's `aria-controls` references a DESCENDANT of the popup host (such as
+      react-select's inner `MenuList` element). Without this carve-out, moving focus into the
+      listbox would blur the external textbox and cause libraries like `react-select` to close the
+      menu on the same interaction that opened it.
+
+    Popups that are not opened from a combobox-like trigger continue to receive their
+    role-appropriate initial focus.
+
+## 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

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/dialog/dialog-content.js

@@ -65,16 +65,30 @@ var Dialog = exports.Dialog = /*#__PURE__*/(0, _react.forwardRef)(function Dialo
       elementRef: ownRef,
       onExitFinish: onExitFinish
     }),
-    showChildren = _useAnimatedVisibilit.showChildren,
+    phase = _useAnimatedVisibilit.phase,
     preset = _useAnimatedVisibilit.preset;
 
+  // Pre-computed phase predicate. `isVisible` means "host element is
+  // mounted and on screen" (any phase except `closed`), used as a dep
+  // signal for the backdrop-click rebind effect so it re-attaches to
+  // the fresh <dialog> element after a close → reopen unmount/remount
+  // cycle.
+  var isVisible = phase !== 'closed';
+
   // Focus wrap
   // Native <dialog>.showModal() traps focus but wraps through <body> at
   // the boundary (A → B → C → body → A). This hook intercepts Tab to
   // wrap directly (A → B → C → A), matching the WAI-ARIA APG pattern.
+  //
+  // Takes `phase` directly: the listener stays attached while
+  // `phase !== 'closed'`, i.e. through the animated-exit window.
+  // Gating on `isOpen` would unbind the listener at the start of an
+  // exit animation while the dialog is still visible, letting focus
+  // escape (WCAG 2.4.3 Focus Order regression).
   (0, _useFocusWrap.useFocusWrap)({
     elementRef: ownRef,
-    role: 'dialog'
+    role: 'dialog',
+    phase: phase
   });
 
   // Open layer observer registration
@@ -120,6 +134,8 @@ var Dialog = exports.Dialog = /*#__PURE__*/(0, _react.forwardRef)(function Dialo
   // Attached via bind-event-listener rather than a React prop so we avoid
   // a11y lint suppressions on the <dialog> element.
   // Keyboard dismiss is already handled natively (Escape → onCancel above).
+  // `isVisible` is in deps so the listener re-binds to the new <dialog>
+  // element after a host unmount / remount cycle.
   (0, _react.useEffect)(function () {
     var dialog = ownRef.current;
     if (!dialog) {
@@ -135,13 +151,26 @@ var Dialog = exports.Dialog = /*#__PURE__*/(0, _react.forwardRef)(function Dialo
         }
       }
     });
-  }, [onClose]);
+  }, [onClose, isVisible]);
 
   // Atomic CSS (Compiled) deduplicates ::backdrop { background-color }
   // into a single class, making it impossible to toggle between two values
   // via cssMap entries. An ID-scoped <style> has higher specificity than
   // any atomic class, so the override always wins.
   var escapedId = CSS.escape(dialogId);
+
+  // The `<dialog>` host element is only rendered while open or its exit
+  // animation is playing. After exit completes the phase returns to
+  // `closed` and we unmount the dialog entirely so it does not leave an
+  // empty `role="dialog"` element in the accessibility tree. The element
+  // re-mounts on the next `isOpen=true` commit; `showModal()` is called
+  // from the existing `useLayoutEffect([isOpen])` on that same commit,
+  // and listeners (cancel, click) re-bind via the `[onClose, isVisible]`
+  // effect re-running after remount (React clears the ref on unmount, so
+  // we need the listener effect to re-run with the fresh element).
+  if (!isVisible) {
+    return null;
+  }
   return /*#__PURE__*/_react.default.createElement("dialog", (0, _extends2.default)({
     ref: combinedRef,
     id: dialogId
@@ -162,5 +191,5 @@ var Dialog = exports.Dialog = /*#__PURE__*/(0, _react.forwardRef)(function Dialo
   }), shouldHideBackdrop &&
   /*#__PURE__*/
   // eslint-disable-next-line @atlaskit/ui-styling-standard/no-global-styles
-  _react.default.createElement("style", null, "#".concat(escapedId, "::backdrop{background-color:transparent}")), showChildren ? children : null);
+  _react.default.createElement("style", null, "#".concat(escapedId, "::backdrop{background-color:transparent}")), children);
 });

package/dist/cjs/dialog-scroll-lock/index.js

@@ -9,14 +9,20 @@ var _browserApis = require("@atlaskit/browser-apis");
 /**
  * __DialogScrollLock__
  *
- * Prevents background page scrolling while mounted. Designed to be rendered
- * inside a `Dialog` so that the scroll lock is automatically removed when the
- * dialog closes (unmounts its children).
+ * Prevents background page scrolling while a dialog is open. Designed to be
+ * rendered inside a `Dialog` and given the same `isOpen` value.
  *
  * Native `<dialog>.showModal()` makes background content _inert_ (not
  * focusable/clickable), but does **not** prevent scroll events from reaching
  * the document body. This component fills that gap by setting
- * `overflow: hidden` on `document.body`.
+ * `overflow: hidden` on `document.body` while `isOpen` is `true`.
+ *
+ * The lock is driven by `isOpen` rather than by mount/unmount so that release
+ * happens synchronously in the same commit that flips `isOpen` to `false`.
+ * Relying on unmount alone was racy: `Dialog` defers the unmount of its
+ * children until the host element's close/toggle event fires, which can be
+ * after a consumer or test observes the dialog as hidden, leading to a
+ * stale `overflow: hidden` window.
  *
  * @example
  * ```tsx
@@ -24,14 +30,18 @@ var _browserApis = require("@atlaskit/browser-apis");
  * import { DialogScrollLock } from '@atlaskit/top-layer/dialog-scroll-lock';
  *
  * <Dialog isOpen={isOpen} onClose={onClose}>
- *   <DialogScrollLock />
+ *   <DialogScrollLock isOpen={isOpen} />
  *   {children}
  * </Dialog>
  * ```
  */
-function DialogScrollLock() {
+function DialogScrollLock(_ref) {
+  var isOpen = _ref.isOpen;
   (0, _react.useLayoutEffect)(function () {
     var _getDocument;
+    if (!isOpen) {
+      return;
+    }
     var body = (_getDocument = (0, _browserApis.getDocument)()) === null || _getDocument === void 0 ? void 0 : _getDocument.body;
     if (!body) {
       return;
@@ -41,6 +51,6 @@ function DialogScrollLock() {
     return function () {
       body.style.overflow = previousOverflow;
     };
-  }, []);
+  }, [isOpen]);
   return null;
 }

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/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

@@ -16,6 +16,8 @@ var _useId = require("@atlaskit/ds-lib/use-id");
  * own `anchor-name` on the trigger element.
  */
 function usePopoverId() {
-  // prefixing for debug clarity in the DOM
+  // `@atlaskit/ds-lib/use-id` already strips characters that React's
+  // `useId` produces (`:`, `«`, `»`) which are invalid in HTML ID
+  // tokens. The `popover-` prefix is purely for DOM debug clarity.
   return "popover-".concat((0, _useId.useId)());
 }

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

@@ -78,11 +78,16 @@ function getAriaForTrigger(_ref) {
   var ariaHasPopup = (0, _roleToAriaHasPopup.roleToAriaHasPopup)({
     role: role
   });
+  // `aria-controls` is set to `undefined` while closed. The `Popover` /
+  // `Dialog` primitives unmount their host element after the exit
+  // animation finishes, so a closed-state `aria-controls` would point
+  // at a node that is not in the DOM. Returning `undefined` here means
+  // JSX spread renders no `aria-controls` attribute on the trigger
+  // until the target exists, avoiding the dangling reference while
+  // keeping the relationship live whenever it is meaningful.
   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
+    'aria-controls': isOpen ? popoverId : undefined
   };
 }

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

@@ -75,7 +75,8 @@ function useAnchorPositionAtPoint(_ref) {
     placement = _ref.placement,
     getPoint = _ref.getPoint,
     _ref$isEnabled = _ref.isEnabled,
-    isEnabled = _ref$isEnabled === void 0 ? true : _ref$isEnabled;
+    isEnabled = _ref$isEnabled === void 0 ? true : _ref$isEnabled,
+    isOpen = _ref.isOpen;
   var syntheticAnchorRef = (0, _react.useRef)(null);
 
   // `getPoint` is kept in a ref so the layout effect can call the
@@ -122,6 +123,7 @@ function useAnchorPositionAtPoint(_ref) {
     anchorRef: syntheticAnchorRef,
     popoverRef: popoverRef,
     placement: placement,
-    isEnabled: isEnabled
+    isEnabled: isEnabled,
+    isOpen: isOpen
   });
 }

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

@@ -221,7 +221,8 @@ function useAnchorPosition(_ref3) {
     _ref3$forceFallbackPo = _ref3.forceFallbackPositioning,
     forceFallbackPositioning = _ref3$forceFallbackPo === void 0 ? false : _ref3$forceFallbackPo,
     _ref3$isEnabled = _ref3.isEnabled,
-    isEnabled = _ref3$isEnabled === void 0 ? true : _ref3$isEnabled;
+    isEnabled = _ref3$isEnabled === void 0 ? true : _ref3$isEnabled,
+    isOpen = _ref3.isOpen;
   var id = (0, _react.useId)();
   // Stabilize `placement` object so the same object literal
   // value returns an object with the same reference
@@ -481,5 +482,5 @@ function useAnchorPosition(_ref3) {
       popover.style.removeProperty('opacity');
     });
     return undoPositioning;
-  }, [anchorRef, popoverRef, stablePlacement, forceFallbackPositioning, isEnabled, id]);
+  }, [anchorRef, popoverRef, stablePlacement, forceFallbackPositioning, isEnabled, id, isOpen]);
 }