@atlaskit/top-layer 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @atlaskit/top-layer
 
+## 1.0.1
+
+### Patch Changes
+
+- [`642a4ddbce9f4`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/642a4ddbce9f4) -
+  [ux] The Select menu is being migrated to the browser top layer. The new behaviour is gated behind
+  the `platform-dst-top-layer` feature flag and ships dark; there are no public API changes for
+  `@atlaskit/react-select` or `@atlaskit/select`.
+
+  Internal-only improvements to support consumer migrations:
+  - Polyfilled the `:popover-open` CSS pseudo-class in the jsdom test polyfill so consumers can
+    assert on popover open state in unit tests without a browser.
+  - Removed a defensive `try/catch` around `element.matches()` in `Popover` that was only needed to
+    work around the missing pseudo-class.
+  - Clarified, via an inline comment in `use-initial-focus`, why the combobox carve-out is kept
+    role-specific (menu / listbox) rather than hoisted above all role checks.
+  - Fixed a unit test for `PopupSelect` top-layer trigger click that incorrectly called `failGate`
+    in `afterEach`, which conflicted with the auto-reset behaviour of
+    `@atlassian/feature-flags-test-utils/mock-gates` and caused the suite to fail.
+
+  No public API or runtime behaviour changes for existing consumers.
+
 ## 1.0.0
 
 ### Major Changes

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

@@ -133,6 +133,12 @@ function getInitialFocusTarget(_ref2) {
       container: container
     });
   }
+
+  // The combobox carve-out is kept role-specific (menu / listbox) rather
+  // than hoisted. Hoisting it over-matched on dialog popups that contain
+  // a nested combobox (e.g. datetime-picker's dialog hosts a react-select),
+  // where the active combobox's `aria-controls` falsely matched the
+  // container and suppressed the dialog's own focus contract.
   if (role === 'menu') {
     if (isComboboxControllingPopup({
       container: container

package/dist/cjs/popover/popover.js

@@ -46,14 +46,36 @@ var styles = {
 var POPUP_ROLES = new Set(['menu', 'listbox', 'dialog', 'alertdialog', 'tree', 'grid']);
 
 /**
- * Unopinionated top-layer primitive. Manages visibility and animation only;
+ * Unopinionated top-layer primitive. Owns visibility and animation only;
  * compose with `useAnchorPosition` / `useWidthFromAnchor` for positioning.
  *
- * `isOpen={true}` calls `showPopover()` (entry via `@starting-style`);
- * `isOpen={false}` calls `hidePopover()` (exit via `allow-discrete`).
+ * ### 🔌 Visibility
  *
- * In `mode="auto"`, the browser can light-dismiss (Escape, click outside).
- * `onClose` fires; the consumer must then set `isOpen` to `false`.
+ * - `isOpen={true}` calls `showPopover()` (entry via `@starting-style`).
+ * - `isOpen={false}` calls `hidePopover()` (exit via `allow-discrete`).
+ *
+ * ### 📜 Browser dismiss is non-cancellable
+ *
+ * Per the popover spec, `beforetoggle` is cancellable on open transitions
+ * only, not on close. Consumers that need to ignore a specific dismiss
+ * (e.g. a click on a logically-associated external trigger) must reconcile
+ * inside their own `onClose` handler by calling `showPopover()` again.
+ * `Popover` does not self-heal so consumers do not pay a reconcile cost
+ * by default.
+ *
+ * - Spec: <https://html.spec.whatwg.org/multipage/popover.html#the-popover-attribute>
+ * - <https://github.com/whatwg/html/issues/8973>
+ *
+ * ### ⚠️ Open from `onClick`, not `onPointerDown`
+ *
+ * The light-dismiss algorithm captures the pointerdown target before the
+ * popover exists and dismisses on the matching pointerup if that target is
+ * not in the popover's ancestor chain. Opening during pointerdown hides
+ * the popover on the next pointerup.
+ *
+ * Legacy triggers that must open on mousedown (e.g. `@atlaskit/react-select`)
+ * should defer the open past the in-flight gesture; see
+ * `Select.openMenuAfterPointerUp`.
  */
 var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Popover(_ref, ref) {
   var children = _ref.children,

package/dist/cjs/testing/polyfill.js

@@ -521,6 +521,18 @@ function handleDocumentKeydown(event) {
 if (typeof HTMLElement !== 'undefined') {
   var schedulePopoverToggle = createToggleScheduler();
 
+  // jsdom throws `SyntaxError` on the `:popover-open` pseudo-class. Answer
+  // it from the polyfill's `data-popover-open` source of truth and
+  // delegate every other selector to the original implementation.
+  // Spec: https://html.spec.whatwg.org/multipage/semantics-other.html#selector-popover-open
+  var originalMatches = Element.prototype.matches;
+  Element.prototype.matches = function patchedMatches(selector) {
+    if (selector === ':popover-open') {
+      return this.hasAttribute('data-popover-open');
+    }
+    return originalMatches.call(this, selector);
+  };
+
   // Spec: https://html.spec.whatwg.org/multipage/popover.html#dom-showpopover
   if (!HTMLElement.prototype.showPopover) {
     HTMLElement.prototype.showPopover = function showPopover() {

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

@@ -127,6 +127,12 @@ function getInitialFocusTarget({
       container
     });
   }
+
+  // The combobox carve-out is kept role-specific (menu / listbox) rather
+  // than hoisted. Hoisting it over-matched on dialog popups that contain
+  // a nested combobox (e.g. datetime-picker's dialog hosts a react-select),
+  // where the active combobox's `aria-controls` falsely matched the
+  // container and suppressed the dialog's own focus contract.
   if (role === 'menu') {
     if (isComboboxControllingPopup({
       container

package/dist/es2019/popover/popover.js

@@ -35,14 +35,36 @@ const styles = {
 const POPUP_ROLES = new Set(['menu', 'listbox', 'dialog', 'alertdialog', 'tree', 'grid']);
 
 /**
- * Unopinionated top-layer primitive. Manages visibility and animation only;
+ * Unopinionated top-layer primitive. Owns visibility and animation only;
  * compose with `useAnchorPosition` / `useWidthFromAnchor` for positioning.
  *
- * `isOpen={true}` calls `showPopover()` (entry via `@starting-style`);
- * `isOpen={false}` calls `hidePopover()` (exit via `allow-discrete`).
+ * ### 🔌 Visibility
  *
- * In `mode="auto"`, the browser can light-dismiss (Escape, click outside).
- * `onClose` fires; the consumer must then set `isOpen` to `false`.
+ * - `isOpen={true}` calls `showPopover()` (entry via `@starting-style`).
+ * - `isOpen={false}` calls `hidePopover()` (exit via `allow-discrete`).
+ *
+ * ### 📜 Browser dismiss is non-cancellable
+ *
+ * Per the popover spec, `beforetoggle` is cancellable on open transitions
+ * only, not on close. Consumers that need to ignore a specific dismiss
+ * (e.g. a click on a logically-associated external trigger) must reconcile
+ * inside their own `onClose` handler by calling `showPopover()` again.
+ * `Popover` does not self-heal so consumers do not pay a reconcile cost
+ * by default.
+ *
+ * - Spec: <https://html.spec.whatwg.org/multipage/popover.html#the-popover-attribute>
+ * - <https://github.com/whatwg/html/issues/8973>
+ *
+ * ### ⚠️ Open from `onClick`, not `onPointerDown`
+ *
+ * The light-dismiss algorithm captures the pointerdown target before the
+ * popover exists and dismisses on the matching pointerup if that target is
+ * not in the popover's ancestor chain. Opening during pointerdown hides
+ * the popover on the next pointerup.
+ *
+ * Legacy triggers that must open on mousedown (e.g. `@atlaskit/react-select`)
+ * should defer the open past the in-flight gesture; see
+ * `Select.openMenuAfterPointerUp`.
  */
 export const Popover = /*#__PURE__*/forwardRef(function Popover({
   children,

package/dist/es2019/testing/polyfill.js

@@ -535,6 +535,18 @@ function handleDocumentKeydown(event) {
 if (typeof HTMLElement !== 'undefined') {
   const schedulePopoverToggle = createToggleScheduler();
 
+  // jsdom throws `SyntaxError` on the `:popover-open` pseudo-class. Answer
+  // it from the polyfill's `data-popover-open` source of truth and
+  // delegate every other selector to the original implementation.
+  // Spec: https://html.spec.whatwg.org/multipage/semantics-other.html#selector-popover-open
+  const originalMatches = Element.prototype.matches;
+  Element.prototype.matches = function patchedMatches(selector) {
+    if (selector === ':popover-open') {
+      return this.hasAttribute('data-popover-open');
+    }
+    return originalMatches.call(this, selector);
+  };
+
   // Spec: https://html.spec.whatwg.org/multipage/popover.html#dom-showpopover
   if (!HTMLElement.prototype.showPopover) {
     HTMLElement.prototype.showPopover = function showPopover() {

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

@@ -127,6 +127,12 @@ function getInitialFocusTarget(_ref2) {
       container: container
     });
   }
+
+  // The combobox carve-out is kept role-specific (menu / listbox) rather
+  // than hoisted. Hoisting it over-matched on dialog popups that contain
+  // a nested combobox (e.g. datetime-picker's dialog hosts a react-select),
+  // where the active combobox's `aria-controls` falsely matched the
+  // container and suppressed the dialog's own focus contract.
   if (role === 'menu') {
     if (isComboboxControllingPopup({
       container: container

package/dist/esm/popover/popover.js

@@ -37,14 +37,36 @@ var styles = {
 var POPUP_ROLES = new Set(['menu', 'listbox', 'dialog', 'alertdialog', 'tree', 'grid']);
 
 /**
- * Unopinionated top-layer primitive. Manages visibility and animation only;
+ * Unopinionated top-layer primitive. Owns visibility and animation only;
  * compose with `useAnchorPosition` / `useWidthFromAnchor` for positioning.
  *
- * `isOpen={true}` calls `showPopover()` (entry via `@starting-style`);
- * `isOpen={false}` calls `hidePopover()` (exit via `allow-discrete`).
+ * ### 🔌 Visibility
  *
- * In `mode="auto"`, the browser can light-dismiss (Escape, click outside).
- * `onClose` fires; the consumer must then set `isOpen` to `false`.
+ * - `isOpen={true}` calls `showPopover()` (entry via `@starting-style`).
+ * - `isOpen={false}` calls `hidePopover()` (exit via `allow-discrete`).
+ *
+ * ### 📜 Browser dismiss is non-cancellable
+ *
+ * Per the popover spec, `beforetoggle` is cancellable on open transitions
+ * only, not on close. Consumers that need to ignore a specific dismiss
+ * (e.g. a click on a logically-associated external trigger) must reconcile
+ * inside their own `onClose` handler by calling `showPopover()` again.
+ * `Popover` does not self-heal so consumers do not pay a reconcile cost
+ * by default.
+ *
+ * - Spec: <https://html.spec.whatwg.org/multipage/popover.html#the-popover-attribute>
+ * - <https://github.com/whatwg/html/issues/8973>
+ *
+ * ### ⚠️ Open from `onClick`, not `onPointerDown`
+ *
+ * The light-dismiss algorithm captures the pointerdown target before the
+ * popover exists and dismisses on the matching pointerup if that target is
+ * not in the popover's ancestor chain. Opening during pointerdown hides
+ * the popover on the next pointerup.
+ *
+ * Legacy triggers that must open on mousedown (e.g. `@atlaskit/react-select`)
+ * should defer the open past the in-flight gesture; see
+ * `Select.openMenuAfterPointerUp`.
  */
 export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
   var children = _ref.children,

package/dist/esm/testing/polyfill.js

@@ -519,6 +519,18 @@ function handleDocumentKeydown(event) {
 if (typeof HTMLElement !== 'undefined') {
   var schedulePopoverToggle = createToggleScheduler();
 
+  // jsdom throws `SyntaxError` on the `:popover-open` pseudo-class. Answer
+  // it from the polyfill's `data-popover-open` source of truth and
+  // delegate every other selector to the original implementation.
+  // Spec: https://html.spec.whatwg.org/multipage/semantics-other.html#selector-popover-open
+  var originalMatches = Element.prototype.matches;
+  Element.prototype.matches = function patchedMatches(selector) {
+    if (selector === ':popover-open') {
+      return this.hasAttribute('data-popover-open');
+    }
+    return originalMatches.call(this, selector);
+  };
+
   // Spec: https://html.spec.whatwg.org/multipage/popover.html#dom-showpopover
   if (!HTMLElement.prototype.showPopover) {
     HTMLElement.prototype.showPopover = function showPopover() {

package/dist/types/popover/popover.d.ts

@@ -5,13 +5,35 @@
 import React from 'react';
 import { type TPopoverForwardedProps } from './types';
 /**
- * Unopinionated top-layer primitive. Manages visibility and animation only;
+ * Unopinionated top-layer primitive. Owns visibility and animation only;
  * compose with `useAnchorPosition` / `useWidthFromAnchor` for positioning.
  *
- * `isOpen={true}` calls `showPopover()` (entry via `@starting-style`);
- * `isOpen={false}` calls `hidePopover()` (exit via `allow-discrete`).
+ * ### 🔌 Visibility
  *
- * In `mode="auto"`, the browser can light-dismiss (Escape, click outside).
- * `onClose` fires; the consumer must then set `isOpen` to `false`.
+ * - `isOpen={true}` calls `showPopover()` (entry via `@starting-style`).
+ * - `isOpen={false}` calls `hidePopover()` (exit via `allow-discrete`).
+ *
+ * ### 📜 Browser dismiss is non-cancellable
+ *
+ * Per the popover spec, `beforetoggle` is cancellable on open transitions
+ * only, not on close. Consumers that need to ignore a specific dismiss
+ * (e.g. a click on a logically-associated external trigger) must reconcile
+ * inside their own `onClose` handler by calling `showPopover()` again.
+ * `Popover` does not self-heal so consumers do not pay a reconcile cost
+ * by default.
+ *
+ * - Spec: <https://html.spec.whatwg.org/multipage/popover.html#the-popover-attribute>
+ * - <https://github.com/whatwg/html/issues/8973>
+ *
+ * ### ⚠️ Open from `onClick`, not `onPointerDown`
+ *
+ * The light-dismiss algorithm captures the pointerdown target before the
+ * popover exists and dismisses on the matching pointerup if that target is
+ * not in the popover's ancestor chain. Opening during pointerdown hides
+ * the popover on the next pointerup.
+ *
+ * Legacy triggers that must open on mousedown (e.g. `@atlaskit/react-select`)
+ * should defer the open past the in-flight gesture; see
+ * `Select.openMenuAfterPointerUp`.
  */
 export declare const Popover: React.ForwardRefExoticComponent<TPopoverForwardedProps & React.RefAttributes<HTMLDivElement>>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/top-layer",
-	"version": "1.0.0",
+	"version": "1.0.1",
 	"description": "Low-level layering primitives based on popover and dialog",
 	"homepage": "https://atlassian.design/components/top-layer",
 	"repository": "https://bitbucket.org/atlassian/atlassian-frontend-mirror",
@@ -51,7 +51,7 @@
 	"devDependencies": {
 		"@af/integration-testing": "workspace:^",
 		"@af/visual-regression": "workspace:^",
-		"@atlaskit/button": "^24.0.0",
+		"@atlaskit/button": "^24.1.0",
 		"@atlaskit/heading": "^6.0.0",
 		"@atlaskit/lozenge": "^14.0.0",
 		"@atlaskit/primitives": "^20.0.0",