@atlaskit/top-layer 0.2.0 → 0.3.0

package/dist/es2019/testing/polyfill.js

@@ -0,0 +1,351 @@
+/* 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({
+  element
+}) {
+  const tag = element.tagName ? element.tagName.toLowerCase() : 'unknown';
+  const id = element.id ? `#${element.id}` : '';
+  const classes = element.classList && element.classList.length > 0 ? `.${Array.from(element.classList).join('.')}` : '';
+  return `<${tag}${id}${classes}>`;
+}
+function createToggleEvent({
+  type,
+  oldState,
+  newState,
+  cancelable
+}) {
+  if (typeof globalThis.ToggleEvent === 'function') {
+    // ToggleEvent is not in lib.dom.d.ts at the time of writing; cast to any for construction.
+    const ToggleEventCtor = globalThis.ToggleEvent;
+    return new ToggleEventCtor(type, {
+      oldState,
+      newState,
+      cancelable,
+      bubbles: false
+    });
+  }
+  const event = new Event(type, {
+    cancelable,
+    bubbles: false
+  });
+  event.oldState = oldState;
+  event.newState = newState;
+  return event;
+}
+function fireToggleEvent({
+  element,
+  type,
+  oldState,
+  newState,
+  cancelable
+}) {
+  return element.dispatchEvent(createToggleEvent({
+    type,
+    oldState,
+    newState,
+    cancelable
+  }));
+}
+function oppositeState({
+  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() {
+  const pending = new Map();
+  return function schedule({
+    element,
+    newState
+  }) {
+    const existing = pending.get(element);
+    if (existing) {
+      // Coalesce: keep the original oldState, update newState
+      pending.set(element, {
+        oldState: existing.oldState,
+        newState
+      });
+      return;
+    }
+    pending.set(element, {
+      oldState: oppositeState({
+        state: newState
+      }),
+      newState
+    });
+
+    // Task queue (setTimeout) — browser fires toggle after microtasks drain, not during
+    setTimeout(() => {
+      const entry = pending.get(element);
+      if (!entry) {
+        return;
+      }
+      pending.delete(element);
+      fireToggleEvent({
+        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() {
+  const pending = new Map();
+  return function schedule({
+    dialog,
+    newState,
+    shouldFireCloseEvent
+  }) {
+    const existing = pending.get(dialog);
+    if (existing) {
+      // Coalesce: keep the original oldState, merge shouldFireCloseEvent
+      pending.set(dialog, {
+        oldState: existing.oldState,
+        newState,
+        shouldFireCloseEvent: existing.shouldFireCloseEvent || shouldFireCloseEvent
+      });
+      return;
+    }
+    pending.set(dialog, {
+      oldState: oppositeState({
+        state: newState
+      }),
+      newState,
+      shouldFireCloseEvent
+    });
+
+    // Browser fires toggle as a task, not synchronously or as a microtask
+    setTimeout(() => {
+      const 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(() => {
+          dialog.dispatchEvent(new Event('close', {
+            bubbles: false,
+            cancelable: false
+          }));
+        }, 0);
+      }
+    }, 0);
+  };
+}
+
+// ─── Popover API ────────────────────────────────────────────────────────────
+
+if (typeof HTMLElement !== 'undefined' && !HTMLElement.prototype.showPopover) {
+  const schedulePopoverToggle = createToggleScheduler();
+  HTMLElement.prototype.showPopover = function showPopover() {
+    if (!this.hasAttribute('popover')) {
+      throw new DOMException(`Failed to execute 'showPopover' on 'HTMLElement': ${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': ${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
+    const 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': ${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) {
+    const 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') {
+  const proto = HTMLDialogElement.prototype;
+  const scheduleDialogToggle = createDialogToggleScheduler();
+  if (typeof proto.showModal !== 'function') {
+    proto.showModal = function showModal() {
+      if (!this.isConnected) {
+        throw new DOMException(`Failed to execute 'showModal' on 'HTMLDialogElement': ${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': ${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() {
+        return this._returnValue === undefined ? '' : this._returnValue;
+      },
+      set(value) {
+        this._returnValue = String(value);
+      },
+      configurable: true,
+      enumerable: true
+    });
+  }
+}

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

@@ -0,0 +1,85 @@
+/* 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
+import { toBeVisible as originalToBeVisible } from '@testing-library/jest-dom/matchers';
+/**
+ * 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(element) {
+    const originalResult = originalToBeVisible.call(this, element);
+    const topLayerState = nearestTopLayerState(element);
+    if (originalResult.pass) {
+      // Original says visible — override if nearest top-layer host is closed.
+      if (topLayerState === 'closed') {
+        return {
+          pass: false,
+          message: () => `expected element to be visible, but it is inside a closed ${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: () => `expected element not to be visible, but it is inside an open ${getNearestTopLayerType(element)}`
+      };
+    }
+    return originalResult;
+  }
+});