@atlaskit/top-layer 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @atlaskit/top-layer
 
+## 0.3.0
+
+### Minor Changes
+
+- [`60e2bb08cd411`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/60e2bb08cd411) -
+  Expose Popover API and HTMLDialogElement jsdom polyfill (and toBeVisible patch) via new
+  testing/polyfill and testing/to-be-visible subpath exports. Adopters can now opt in to the
+  polyfill in their jest setup with a single import.
+
 ## 0.2.0
 
 ### Minor Changes

package/dist/cjs/testing/polyfill.js

@@ -0,0 +1,347 @@
+"use strict";
+
+/* eslint-disable compat/compat */
+/**
+ * Popover API & HTMLDialogElement polyfills for jsdom.
+ *
+ * jsdom does not implement the Popover API or the HTMLDialogElement methods
+ * (showModal, show, close). This polyfill provides faithful implementations,
+ * including timing semantics validated against Chromium via Playwright.
+ *
+ * Behaviour:
+ *  - beforetoggle: sync, cancelable on show only. toggle: async task, not cancelable.
+ *  - Rapid show/hide coalesces into one toggle event (originalOldState to finalNewState).
+ *  - Dialog: showModal/show fire beforetoggle+toggle. close fires toggle then close event.
+ *  - Popover open state tracked via `data-popover-open` (no `:popover-open` in jsdom).
+ *
+ * Companion `toBeVisible` patch lives at `./to-be-visible`.
+ *
+ * Importing this module has the side-effect of patching the relevant
+ * prototypes. It is safe to import multiple times; each branch is guarded
+ * to avoid overwriting native implementations or re-patching.
+ */
+
+/**
+ * e.g. `<div#my-id.class-a.class-b>`
+ */
+function describeElement(_ref) {
+  var element = _ref.element;
+  var tag = element.tagName ? element.tagName.toLowerCase() : 'unknown';
+  var id = element.id ? "#".concat(element.id) : '';
+  var classes = element.classList && element.classList.length > 0 ? ".".concat(Array.from(element.classList).join('.')) : '';
+  return "<".concat(tag).concat(id).concat(classes, ">");
+}
+function createToggleEvent(_ref2) {
+  var type = _ref2.type,
+    oldState = _ref2.oldState,
+    newState = _ref2.newState,
+    cancelable = _ref2.cancelable;
+  if (typeof globalThis.ToggleEvent === 'function') {
+    // ToggleEvent is not in lib.dom.d.ts at the time of writing; cast to any for construction.
+    var ToggleEventCtor = globalThis.ToggleEvent;
+    return new ToggleEventCtor(type, {
+      oldState: oldState,
+      newState: newState,
+      cancelable: cancelable,
+      bubbles: false
+    });
+  }
+  var event = new Event(type, {
+    cancelable: cancelable,
+    bubbles: false
+  });
+  event.oldState = oldState;
+  event.newState = newState;
+  return event;
+}
+function fireToggleEvent(_ref3) {
+  var element = _ref3.element,
+    type = _ref3.type,
+    oldState = _ref3.oldState,
+    newState = _ref3.newState,
+    cancelable = _ref3.cancelable;
+  return element.dispatchEvent(createToggleEvent({
+    type: type,
+    oldState: oldState,
+    newState: newState,
+    cancelable: cancelable
+  }));
+}
+function oppositeState(_ref4) {
+  var state = _ref4.state;
+  if (state === 'open') {
+    return 'closed';
+  }
+  return 'open';
+}
+
+// Coalesces rapid show/hide into one toggle event per element.
+// Uses setTimeout (task) not Promise.resolve (microtask) to match browser timing.
+function createToggleScheduler() {
+  var pending = new Map();
+  return function schedule(_ref5) {
+    var element = _ref5.element,
+      newState = _ref5.newState;
+    var existing = pending.get(element);
+    if (existing) {
+      // Coalesce: keep the original oldState, update newState
+      pending.set(element, {
+        oldState: existing.oldState,
+        newState: newState
+      });
+      return;
+    }
+    pending.set(element, {
+      oldState: oppositeState({
+        state: newState
+      }),
+      newState: newState
+    });
+
+    // Task queue (setTimeout) — browser fires toggle after microtasks drain, not during
+    setTimeout(function () {
+      var entry = pending.get(element);
+      if (!entry) {
+        return;
+      }
+      pending.delete(element);
+      fireToggleEvent({
+        element: element,
+        type: 'toggle',
+        oldState: entry.oldState,
+        newState: entry.newState,
+        cancelable: false
+      });
+    }, 0);
+  };
+}
+
+// Like createToggleScheduler but also fires a close event as a separate task after toggle.
+function createDialogToggleScheduler() {
+  var pending = new Map();
+  return function schedule(_ref6) {
+    var dialog = _ref6.dialog,
+      newState = _ref6.newState,
+      shouldFireCloseEvent = _ref6.shouldFireCloseEvent;
+    var existing = pending.get(dialog);
+    if (existing) {
+      // Coalesce: keep the original oldState, merge shouldFireCloseEvent
+      pending.set(dialog, {
+        oldState: existing.oldState,
+        newState: newState,
+        shouldFireCloseEvent: existing.shouldFireCloseEvent || shouldFireCloseEvent
+      });
+      return;
+    }
+    pending.set(dialog, {
+      oldState: oppositeState({
+        state: newState
+      }),
+      newState: newState,
+      shouldFireCloseEvent: shouldFireCloseEvent
+    });
+
+    // Browser fires toggle as a task, not synchronously or as a microtask
+    setTimeout(function () {
+      var entry = pending.get(dialog);
+      if (!entry) {
+        return;
+      }
+      pending.delete(dialog);
+      fireToggleEvent({
+        element: dialog,
+        type: 'toggle',
+        oldState: entry.oldState,
+        newState: entry.newState,
+        cancelable: false
+      });
+      if (entry.shouldFireCloseEvent) {
+        // Browser fires close as a separate task after toggle
+        setTimeout(function () {
+          dialog.dispatchEvent(new Event('close', {
+            bubbles: false,
+            cancelable: false
+          }));
+        }, 0);
+      }
+    }, 0);
+  };
+}
+
+// ─── Popover API ────────────────────────────────────────────────────────────
+
+if (typeof HTMLElement !== 'undefined' && !HTMLElement.prototype.showPopover) {
+  var schedulePopoverToggle = createToggleScheduler();
+  HTMLElement.prototype.showPopover = function showPopover() {
+    if (!this.hasAttribute('popover')) {
+      throw new DOMException("Failed to execute 'showPopover' on 'HTMLElement': ".concat(describeElement({
+        element: this
+      }), " is not a popover element. Ensure the element has a 'popover' attribute (e.g. <div popover>)."), 'NotSupportedError');
+    }
+    if (!this.isConnected) {
+      throw new DOMException("Failed to execute 'showPopover' on 'HTMLElement': ".concat(describeElement({
+        element: this
+      }), " is not connected to the document. Ensure the element has been added to the DOM (e.g. via render() or document.body.appendChild()) before calling showPopover()."), 'InvalidStateError');
+    }
+    if (this.hasAttribute('data-popover-open')) {
+      return; // already showing — no-op
+    }
+
+    // sync, cancelable on show only
+    var allowed = fireToggleEvent({
+      element: this,
+      type: 'beforetoggle',
+      oldState: 'closed',
+      newState: 'open',
+      cancelable: true
+    });
+    if (!allowed) {
+      return;
+    }
+    this.setAttribute('data-popover-open', '');
+    schedulePopoverToggle({
+      element: this,
+      newState: 'open'
+    });
+  };
+  HTMLElement.prototype.hidePopover = function hidePopover() {
+    if (!this.hasAttribute('popover')) {
+      throw new DOMException("Failed to execute 'hidePopover' on 'HTMLElement': ".concat(describeElement({
+        element: this
+      }), " is not a popover element. Ensure the element has a 'popover' attribute (e.g. <div popover>)."), 'NotSupportedError');
+    }
+    // Browser does not throw for disconnected elements on hide — just no-op
+    if (!this.isConnected || !this.hasAttribute('data-popover-open')) {
+      return;
+    }
+
+    // not cancelable on hide
+    fireToggleEvent({
+      element: this,
+      type: 'beforetoggle',
+      oldState: 'open',
+      newState: 'closed',
+      cancelable: false
+    });
+    this.removeAttribute('data-popover-open');
+    schedulePopoverToggle({
+      element: this,
+      newState: 'closed'
+    });
+  };
+  HTMLElement.prototype.togglePopover = function togglePopover(force) {
+    var isOpen = this.hasAttribute('data-popover-open');
+    if (typeof force === 'boolean') {
+      if (force && !isOpen) {
+        this.showPopover();
+      } else if (!force && isOpen) {
+        this.hidePopover();
+      }
+      return force;
+    }
+    if (isOpen) {
+      this.hidePopover();
+      return false;
+    }
+    this.showPopover();
+    return true;
+  };
+}
+
+// ─── HTMLDialogElement ──────────────────────────────────────────────────────
+
+if (typeof HTMLDialogElement !== 'undefined') {
+  var proto = HTMLDialogElement.prototype;
+  var scheduleDialogToggle = createDialogToggleScheduler();
+  if (typeof proto.showModal !== 'function') {
+    proto.showModal = function showModal() {
+      if (!this.isConnected) {
+        throw new DOMException("Failed to execute 'showModal' on 'HTMLDialogElement': ".concat(describeElement({
+          element: this
+        }), " is not connected to the document. Ensure the element has been added to the DOM (e.g. via render() or document.body.appendChild()) before calling showModal()."), 'InvalidStateError');
+      }
+      if (this.hasAttribute('open')) {
+        if (this._isModal) {
+          return; // already modal — no-op
+        }
+        throw new DOMException("Failed to execute 'showModal' on 'HTMLDialogElement': ".concat(describeElement({
+          element: this
+        }), " already has an 'open' attribute, and therefore cannot be opened modally. The dialog was likely opened non-modally with .show(). Call .close() first, then .showModal()."), 'InvalidStateError');
+      }
+      fireToggleEvent({
+        element: this,
+        type: 'beforetoggle',
+        oldState: 'closed',
+        newState: 'open',
+        cancelable: false
+      });
+      this.setAttribute('open', '');
+      this._isModal = true;
+      scheduleDialogToggle({
+        dialog: this,
+        newState: 'open',
+        shouldFireCloseEvent: false
+      });
+    };
+  }
+  if (typeof proto.show !== 'function') {
+    proto.show = function show() {
+      // Browser does not throw for disconnected elements on show — just no-op
+      if (!this.isConnected || this.hasAttribute('open')) {
+        return;
+      }
+      fireToggleEvent({
+        element: this,
+        type: 'beforetoggle',
+        oldState: 'closed',
+        newState: 'open',
+        cancelable: false
+      });
+      this.setAttribute('open', '');
+      this._isModal = false;
+      scheduleDialogToggle({
+        dialog: this,
+        newState: 'open',
+        shouldFireCloseEvent: false
+      });
+    };
+  }
+  if (typeof proto.close !== 'function') {
+    proto.close = function close(returnValue) {
+      if (!this.hasAttribute('open')) {
+        return; // already closed — no-op
+      }
+
+      // Sync beforetoggle (not cancelable) — matches browser behavior
+      fireToggleEvent({
+        element: this,
+        type: 'beforetoggle',
+        oldState: 'open',
+        newState: 'closed',
+        cancelable: false
+      });
+      this.removeAttribute('open');
+      this._isModal = false;
+      if (returnValue !== undefined) {
+        this.returnValue = returnValue;
+      }
+      scheduleDialogToggle({
+        dialog: this,
+        newState: 'closed',
+        shouldFireCloseEvent: true
+      });
+    };
+  }
+  if (!('returnValue' in proto)) {
+    Object.defineProperty(proto, 'returnValue', {
+      get: function get() {
+        return this._returnValue === undefined ? '' : this._returnValue;
+      },
+      set: function set(value) {
+        this._returnValue = String(value);
+      },
+      configurable: true,
+      enumerable: true
+    });
+  }
+}

package/dist/cjs/testing/to-be-visible.js

@@ -0,0 +1,92 @@
+"use strict";
+
+var _matchers = require("@testing-library/jest-dom/matchers");
+/* eslint-disable compat/compat */
+/* global expect */
+/**
+ * Patches `toBeVisible()` to understand popover and dialog visibility.
+ *
+ * jest-dom's `toBeVisible()` does not know about the Popover API. In real
+ * browsers the UA stylesheet hides `[popover]` with `display: none`, but
+ * jsdom has no such stylesheet — so closed popovers incorrectly appear visible.
+ *
+ * Raw jest-dom results in jsdom:
+ *
+ *   closed popover / child  → true  (WRONG — should be false)
+ *   open popover / child    → true  (correct)
+ *   closed dialog / child   → false (correct — jsdom natively hides <dialog>)
+ *   open dialog / child     → true  (correct)
+ *
+ * We correct both false positives and false negatives:
+ *   1. Delegate to the original first.
+ *   2. If it says "visible" → check for closed top-layer hosts (false positive).
+ *   3. If it says "not visible" → check for open top-layer hosts (false negative).
+ *
+ * Must load via `setupFilesAfterEnv` (after jest-dom registers its matchers).
+ * Polyfills live in `./polyfill` (loaded via `setupFiles`).
+ */
+
+// Delegating to jest-dom's matcher; types come from @testing-library/jest-dom.
+// eslint-disable-next-line import/no-extraneous-dependencies
+
+/**
+ * Finds the nearest popover or dialog ancestor (including the element itself)
+ * and returns its state: 'open', 'closed', or null if no top-layer ancestor exists.
+ *
+ * Checking the *nearest* ancestor handles nesting correctly:
+ * a closed popover inside an open popover → nearest is closed → not visible.
+ */
+function nearestTopLayerState(element) {
+  if (!element) {
+    return null;
+  }
+  if (element.hasAttribute('popover')) {
+    return element.hasAttribute('data-popover-open') ? 'open' : 'closed';
+  }
+  if (element.nodeName === 'DIALOG') {
+    return element.hasAttribute('open') ? 'open' : 'closed';
+  }
+  return nearestTopLayerState(element.parentElement);
+}
+function getNearestTopLayerType(element) {
+  if (!element.closest) {
+    return 'top-layer element';
+  }
+  if (element.closest('[popover]')) {
+    return 'popover';
+  }
+  return 'dialog';
+}
+
+// `expect` is registered globally by jest before this file runs.
+
+expect.extend({
+  toBeVisible: function toBeVisible(element) {
+    var originalResult = _matchers.toBeVisible.call(this, element);
+    var topLayerState = nearestTopLayerState(element);
+    if (originalResult.pass) {
+      // Original says visible — override if nearest top-layer host is closed.
+      if (topLayerState === 'closed') {
+        return {
+          pass: false,
+          message: function message() {
+            return "expected element to be visible, but it is inside a closed ".concat(getNearestTopLayerType(element));
+          }
+        };
+      }
+      return originalResult;
+    }
+
+    // Original says not visible — override if nearest top-layer host is open.
+    // jsdom may hide [popover] elements even when they are logically open.
+    if (topLayerState === 'open') {
+      return {
+        pass: true,
+        message: function message() {
+          return "expected element not to be visible, but it is inside an open ".concat(getNearestTopLayerType(element));
+        }
+      };
+    }
+    return originalResult;
+  }
+});