@atlaskit/top-layer 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @atlaskit/top-layer
 
+## 0.4.0
+
+### Minor Changes
+
+- [`58c9d421e96b1`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/58c9d421e96b1) -
+  Improves the jsdom test polyfill (`testing/polyfill`) to better match WHATWG popover spec
+  semantics:
+  - Adds the `el.popover` IDL getter/setter so feature-detection (`supportsPopoverHint()` etc) works
+    in jsdom and `popover="hint"` is exercised in tests rather than silently falling back to
+    `popover="auto"`.
+  - Implements a separate hint stack so opening a `hint` does not close open `auto` popovers;
+    opening an `auto` closes all hints; light-dismiss and Escape walk both stacks per spec.
+  - Implements proper "topmost popover ancestor" lookup that walks both DOM ancestry and the invoker
+    chain (via `popovertarget`), so opening a popover from a button inside another popover does not
+    close the parent.
+  - Light-dismiss now uses pointerdown + pointerup (with `mousedown` + `mouseup` fallback) and a
+    same-target check so drag-out and drag-in gestures do not dismiss popovers.
+  - `togglePopover()` now returns the actual resulting open state.
+  - Per-method patching (`showPopover` / `hidePopover` / `togglePopover`) so partial native support
+    in future jsdom versions still patches the missing methods.
+  - Disconnected popovers are pruned from the open stacks (defends against test-pollution).
+  - Clears any inline `opacity: 0` set by callers (such as `use-anchor-positioning`'s
+    "hide-until-measured" guard) once the open toggle fires, since jsdom does not deliver
+    `ResizeObserver` callbacks.
+  - Treats `popover=""` (empty value) as `auto` per spec.
+
 ## 0.3.0
 
 ### Minor Changes

package/dist/cjs/testing/polyfill.js

@@ -1,5 +1,6 @@
 "use strict";
 
+var _bindEventListener = require("bind-event-listener");
 /* eslint-disable compat/compat */
 /**
  * Popover API & HTMLDialogElement polyfills for jsdom.
@@ -9,10 +10,15 @@
  * including timing semantics validated against Chromium via Playwright.
  *
  * Behaviour:
- *  - beforetoggle: sync, cancelable on show only. toggle: async task, not cancelable.
+ *  - beforetoggle: sync, cancelable on popover show only. toggle: async task, never 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).
+ *  - Auto popovers: maintain an open stack, perform light-dismiss on document mousedown
+ *    outside the open chain, and dismiss the topmost on Escape.
+ *  - On open, removes any inline `opacity: 0` from the popover element so callers that
+ *    rely on a `ResizeObserver` reveal callback (e.g. `use-anchor-positioning`) become
+ *    visible in jsdom, where layout-driven RO callbacks never fire.
  *
  * Companion `toBeVisible` patch lives at `./to-be-visible`.
  *
@@ -169,86 +175,550 @@ function createDialogToggleScheduler() {
 }
 
 // ─── Popover API ────────────────────────────────────────────────────────────
+// Spec: https://html.spec.whatwg.org/multipage/popover.html
 
-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({
+// `popover` attribute valid values. Empty / "auto" -> "auto"; unknown -> "manual".
+// Spec: https://html.spec.whatwg.org/multipage/popover.html#attr-popover
+
+function getPopoverMode(_ref7) {
+  var element = _ref7.element;
+  if (!element.hasAttribute('popover')) {
+    return null;
+  }
+  var raw = element.getAttribute('popover');
+  if (raw === null || raw === '' || raw === 'auto') {
+    return 'auto';
+  }
+  if (raw === 'hint') {
+    return 'hint';
+  }
+  return 'manual';
+}
+
+// IDL property: `el.popover` reflects the popover content attribute. Setter
+// writes verbatim; getter canonicalises (unknown -> "manual", empty -> "auto").
+// Spec: https://html.spec.whatwg.org/multipage/popover.html#dom-popover
+
+if (typeof HTMLElement !== 'undefined' && !Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'popover')) {
+  Object.defineProperty(HTMLElement.prototype, 'popover', {
+    configurable: true,
+    enumerable: true,
+    get: function get() {
+      return getPopoverMode({
         element: this
-      }), " is not a popover element. Ensure the element has a 'popover' attribute (e.g. <div popover>)."), 'NotSupportedError');
+      });
+    },
+    set: function set(value) {
+      if (value === null) {
+        this.removeAttribute('popover');
+        return;
+      }
+      // Per spec, the IDL setter writes the value verbatim; the getter then
+      // canonicalises (so setting an unknown value is reflected as "manual"
+      // only when read back, but the attribute keeps the raw string).
+      this.setAttribute('popover', String(value));
     }
-    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');
+  });
+}
+
+// Open auto popovers in open-order. Used for light-dismiss, Escape, and
+// hide-all-popovers-until on new auto opens.
+// Spec: https://html.spec.whatwg.org/multipage/popover.html#showing-auto-popover-list
+var openAutoStack = [];
+
+// Open hint popovers in open-order. Hints have their own stack: hint closes
+// other hints, auto closes all hints, hint never closes autos.
+// Spec: https://html.spec.whatwg.org/multipage/popover.html#showing-hint-popover-list
+var openHintStack = [];
+function isPopoverOpen(_ref8) {
+  var element = _ref8.element;
+  return element.hasAttribute('data-popover-open');
+}
+
+// Stack lookup: returns the stack the element belongs to (or null for manual /
+// non-popovers). Used by hide-handlers to remove from the correct stack and by
+// dismissal logic to find the topmost relevant popover.
+function stackForMode(_ref9) {
+  var mode = _ref9.mode;
+  if (mode === 'auto') {
+    return openAutoStack;
+  }
+  if (mode === 'hint') {
+    return openHintStack;
+  }
+  return null;
+}
+
+// Polyfill-only. Real browsers reveal the popover once `ResizeObserver`
+// callbacks fire after the first layout pass. jsdom has no layout, so we clear
+// any inline `opacity: 0` (set by callers like `use-anchor-positioning`) once
+// the open toggle has fired.
+function clearOpacityOnOpenToggle(_ref0) {
+  var element = _ref0.element;
+  var unbind = (0, _bindEventListener.bind)(element, {
+    type: 'toggle',
+    listener: function listener(event) {
+      var toggleEvent = event;
+      if (toggleEvent.newState !== 'open') {
+        return;
+      }
+      element.style.removeProperty('opacity');
+      unbind();
     }
-    if (this.hasAttribute('data-popover-open')) {
-      return; // already showing — no-op
+  });
+}
+
+// Spec: "topmost popover ancestor" walks both DOM ancestry AND the invoker
+// chain (an invoker is a button whose `popovertarget` references an open
+// popover). When opening popover B from a button inside popover A, A is
+// considered B's ancestor and stays open. This walks ancestors of the target,
+// hopping through any invoker references discovered along the way.
+// Find a popover's invoker: an element with `popovertarget=<popover.id>`.
+// Spec: https://html.spec.whatwg.org/multipage/popover.html#popover-target-element
+function findInvokerForPopover(_ref1) {
+  var popover = _ref1.popover;
+  if (!popover.id || !popover.ownerDocument) {
+    return null;
+  }
+  var escaped = (typeof CSS !== 'undefined' && CSS.escape ? CSS.escape : String)(popover.id);
+  var selector = "[popovertarget=\"".concat(escaped, "\"]");
+  return popover.ownerDocument.querySelector(selector);
+}
+
+// True if `candidate` is reachable from `start` via DOM ancestry plus invoker
+// hops. Spec: https://html.spec.whatwg.org/multipage/popover.html#topmost-popover-ancestor
+function reachesViaAncestryOrInvoker(_ref10) {
+  var start = _ref10.start,
+    candidate = _ref10.candidate;
+  var found = walkAncestorChain({
+    start: start,
+    visitor: function visitor(_ref11) {
+      var node = _ref11.node;
+      if (node === candidate) {
+        return true;
+      }
+      // Hop into the invoked popover's chain when this node is an invoker.
+      if (node instanceof HTMLElement) {
+        var popovertarget = node.getAttribute('popovertarget');
+        if (popovertarget && node.ownerDocument) {
+          var referenced = node.ownerDocument.getElementById(popovertarget);
+          if (referenced && referenced !== node) {
+            if (reachesViaAncestryOrInvoker({
+              start: referenced,
+              candidate: candidate
+            })) {
+              return true;
+            }
+          }
+        }
+      }
+      return null;
     }
+  });
+  return found === true;
+}
 
-    // sync, cancelable on show only
-    var allowed = fireToggleEvent({
-      element: this,
-      type: 'beforetoggle',
-      oldState: 'closed',
-      newState: 'open',
-      cancelable: true
+// Is `candidate` an ancestor of `target` via DOM nesting OR invoker chain?
+// Spec: https://html.spec.whatwg.org/multipage/popover.html#topmost-popover-ancestor
+function isInChainTo(_ref12) {
+  var candidate = _ref12.candidate,
+    target = _ref12.target;
+  if (!(target instanceof Node)) {
+    return false;
+  }
+  if (reachesViaAncestryOrInvoker({
+    start: target,
+    candidate: candidate
+  })) {
+    return true;
+  }
+  // If target is itself a popover, also walk its invoker's chain (a button
+  // elsewhere in the DOM that has `popovertarget=<target.id>`).
+  if (target instanceof HTMLElement && target.hasAttribute('popover')) {
+    var invoker = findInvokerForPopover({
+      popover: target
     });
-    if (!allowed) {
-      return;
+    if (invoker && reachesViaAncestryOrInvoker({
+      start: invoker,
+      candidate: candidate
+    })) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// Hide every popover in `stack` that is not an ancestor of `target`. With a
+// null target, closes the entire stack.
+// Spec: https://html.spec.whatwg.org/multipage/popover.html#hide-all-popovers-until
+function hidePopoversInStackNotInChainTo(_ref13) {
+  var stack = _ref13.stack,
+    target = _ref13.target;
+  var snapshot = stack.slice();
+  for (var i = snapshot.length - 1; i >= 0; i -= 1) {
+    var popover = snapshot[i];
+    if (isInChainTo({
+      candidate: popover,
+      target: target
+    })) {
+      break;
+    }
+    popover.hidePopover();
+  }
+}
+
+// Two-phase light-dismiss: pointerdown stores the nearest open popover for
+// the target; pointerup dismisses popovers that are not in that popover's
+// chain when the same target is hit. Drag-out / drag-in does not dismiss.
+// Spec: https://html.spec.whatwg.org/multipage/popover.html#light-dismiss-open-popovers
+var pointerdownState = {
+  target: null
+};
+
+// If `node` is an invoker for an open popover, return that popover.
+// Spec: https://html.spec.whatwg.org/multipage/popover.html#popover-target-element
+function invokedOpenPopover(_ref14) {
+  var node = _ref14.node;
+  if (!(node instanceof HTMLElement)) {
+    return null;
+  }
+  var popovertarget = node.getAttribute('popovertarget');
+  if (!popovertarget || !node.ownerDocument) {
+    return null;
+  }
+  var referenced = node.ownerDocument.getElementById(popovertarget);
+  if (!referenced || referenced === node || !isPopoverOpen({
+    element: referenced
+  })) {
+    return null;
+  }
+  return referenced;
+}
+
+// Cycle-safe ancestor walker. Returns the first non-null `visitor` result.
+function walkAncestorChain(_ref15) {
+  var start = _ref15.start,
+    visitor = _ref15.visitor;
+  var seen = new Set();
+  function step(node) {
+    if (!node || seen.has(node)) {
+      return null;
     }
-    this.setAttribute('data-popover-open', '');
-    schedulePopoverToggle({
-      element: this,
-      newState: 'open'
+    seen.add(node);
+    var result = visitor({
+      node: node
     });
-  };
-  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');
+    if (result !== null) {
+      return result;
     }
-    // Browser does not throw for disconnected elements on hide — just no-op
-    if (!this.isConnected || !this.hasAttribute('data-popover-open')) {
-      return;
+    return step(node.parentNode);
+  }
+  return step(start);
+}
+
+// Spec: https://html.spec.whatwg.org/multipage/popover.html#nearest-inclusive-open-popover
+function nearestOpenPopover(_ref16) {
+  var target = _ref16.target;
+  return walkAncestorChain({
+    start: target,
+    visitor: function visitor(_ref17) {
+      var node = _ref17.node;
+      if (node instanceof HTMLElement && isPopoverOpen({
+        element: node
+      })) {
+        return node;
+      }
+      return invokedOpenPopover({
+        node: node
+      });
+    }
+  });
+}
+function handleDocumentPointerdown(event) {
+  if (openAutoStack.length === 0 && openHintStack.length === 0) {
+    return;
+  }
+  var target = event.target instanceof Node ? event.target : null;
+  pointerdownState.target = nearestOpenPopover({
+    target: target
+  });
+}
+function handleDocumentPointerup(event) {
+  if (openAutoStack.length === 0 && openHintStack.length === 0) {
+    pointerdownState.target = null;
+    return;
+  }
+  var target = event.target instanceof Node ? event.target : null;
+  var ancestor = nearestOpenPopover({
+    target: target
+  });
+  var sameTarget = ancestor === pointerdownState.target;
+  pointerdownState.target = null;
+  if (!sameTarget) {
+    // User pointerdowned inside a popover and released elsewhere (or vice
+    // versa). Treat as a drag and do not dismiss per spec.
+    return;
+  }
+  // Hints are dismissed first (they sit "above" autos for dismissal purposes
+  // even though they live in their own stack), then autos. When ancestor is a
+  // hint, autos are unaffected; when ancestor is an auto or null, hints close
+  // entirely (because no hint is the target's ancestor).
+  var ancestorMode = ancestor ? getPopoverMode({
+    element: ancestor
+  }) : null;
+  if (ancestorMode === 'hint') {
+    hidePopoversInStackNotInChainTo({
+      stack: openHintStack,
+      target: target
+    });
+    return;
+  }
+  hidePopoversInStackNotInChainTo({
+    stack: openHintStack,
+    target: null
+  });
+  hidePopoversInStackNotInChainTo({
+    stack: openAutoStack,
+    target: target
+  });
+}
+
+// Topmost still-connected popover in `stack`, pruning disconnected entries
+// (test pollution where a popover was removed from the DOM without hidePopover).
+// Polyfill-only defensive cleanup; not in the spec.
+function topmostConnected(_ref18) {
+  var stack = _ref18.stack;
+  while (stack.length > 0) {
+    var candidate = stack[stack.length - 1];
+    if (candidate.isConnected) {
+      return candidate;
     }
+    stack.pop();
+  }
+  return null;
+}
 
-    // not cancelable on hide
-    fireToggleEvent({
-      element: this,
-      type: 'beforetoggle',
-      oldState: 'open',
-      newState: 'closed',
-      cancelable: false
+// Escape closes the topmost open popover. Hints are dismissed before autos.
+// Spec: https://html.spec.whatwg.org/multipage/popover.html#close-watcher
+function handleDocumentKeydown(event) {
+  if (event.key !== 'Escape') {
+    return;
+  }
+  var topHint = topmostConnected({
+    stack: openHintStack
+  });
+  if (topHint) {
+    topHint.hidePopover();
+    return;
+  }
+  var topAuto = topmostConnected({
+    stack: openAutoStack
+  });
+  if (topAuto) {
+    topAuto.hidePopover();
+  }
+}
+if (typeof HTMLElement !== 'undefined') {
+  var schedulePopoverToggle = createToggleScheduler();
+
+  // Spec: https://html.spec.whatwg.org/multipage/popover.html#dom-showpopover
+  if (!HTMLElement.prototype.showPopover) {
+    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 (isPopoverOpen({
+        element: this
+      })) {
+        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;
+      }
+
+      // Spec-driven dismissal of popovers in other stacks before opening:
+      // - opening an `auto`: close all hints; close autos not in the new
+      //   popover's ancestor chain.
+      // - opening a `hint`:  close hints not in the new popover's chain;
+      //   leave autos alone.
+      // - opening a `manual`: leave both stacks untouched.
+      var mode = getPopoverMode({
+        element: this
+      });
+      if (mode === 'auto') {
+        hidePopoversInStackNotInChainTo({
+          stack: openHintStack,
+          target: null
+        });
+        hidePopoversInStackNotInChainTo({
+          stack: openAutoStack,
+          target: this
+        });
+      } else if (mode === 'hint') {
+        hidePopoversInStackNotInChainTo({
+          stack: openHintStack,
+          target: this
+        });
+      }
+      this.setAttribute('data-popover-open', '');
+      var stack = stackForMode({
+        mode: mode
+      });
+      if (stack && !stack.includes(this)) {
+        stack.push(this);
+      }
+      clearOpacityOnOpenToggle({
+        element: this
+      });
+      schedulePopoverToggle({
+        element: this,
+        newState: 'open'
+      });
+    };
+  }
+
+  // Spec: https://html.spec.whatwg.org/multipage/popover.html#dom-hidepopover
+  if (!HTMLElement.prototype.hidePopover) {
+    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. No-op.
+      if (!this.isConnected || !isPopoverOpen({
+        element: this
+      })) {
+        return;
+      }
+
+      // not cancelable on hide
+      fireToggleEvent({
+        element: this,
+        type: 'beforetoggle',
+        oldState: 'open',
+        newState: 'closed',
+        cancelable: false
+      });
+      this.removeAttribute('data-popover-open');
+      var stack = stackForMode({
+        mode: getPopoverMode({
+          element: this
+        })
+      });
+      if (stack) {
+        var stackIndex = stack.indexOf(this);
+        if (stackIndex !== -1) {
+          stack.splice(stackIndex, 1);
+        }
+      }
+      schedulePopoverToggle({
+        element: this,
+        newState: 'closed'
+      });
+    };
+  }
+
+  // Spec: https://html.spec.whatwg.org/multipage/popover.html#dom-togglepopover
+  if (!HTMLElement.prototype.togglePopover) {
+    HTMLElement.prototype.togglePopover = function togglePopover(force) {
+      var wasOpen = isPopoverOpen({
+        element: this
+      });
+      if (typeof force === 'boolean') {
+        if (force && !wasOpen) {
+          this.showPopover();
+        } else if (!force && wasOpen) {
+          this.hidePopover();
+        }
+      } else if (wasOpen) {
+        this.hidePopover();
+      } else {
+        this.showPopover();
+      }
+
+      // Return the actual resulting state, which differs from `force` when
+      // `beforetoggle` was preventDefaulted on show.
+      return isPopoverOpen({
+        element: this
+      });
+    };
+  }
+
+  // Document-level light-dismiss for `popover="auto"` and `popover="hint"`.
+  // Spec uses pointerdown + pointerup with same-target check; we also wire
+  // `mousedown` + `mouseup` because jsdom does not fire pointer events for
+  // fireEvent.click() / userEvent.click() in older jsdom versions.
+
+  if (typeof document !== 'undefined' && !document.__atTopLayerLightDismiss) {
+    document.__atTopLayerLightDismiss = true;
+
+    // capture phase so application handlers cannot stop propagation before us
+    var pointerdownAdapter = function pointerdownAdapter(event) {
+      return handleDocumentPointerdown(event);
+    };
+    var pointerupAdapter = function pointerupAdapter(event) {
+      return handleDocumentPointerup(event);
+    };
+    (0, _bindEventListener.bind)(document, {
+      type: 'pointerdown',
+      listener: pointerdownAdapter,
+      options: {
+        capture: true
+      }
     });
-    this.removeAttribute('data-popover-open');
-    schedulePopoverToggle({
-      element: this,
-      newState: 'closed'
+    (0, _bindEventListener.bind)(document, {
+      type: 'pointerup',
+      listener: pointerupAdapter,
+      options: {
+        capture: true
+      }
     });
-  };
-  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();
+    // Fallback for environments / fireEvent paths that fire mouse events
+    // only. The same handlers work for MouseEvent because we only read
+    // `target`. PointerEvent extends MouseEvent so the runtime cast is safe.
+    (0, _bindEventListener.bind)(document, {
+      type: 'mousedown',
+      listener: pointerdownAdapter,
+      options: {
+        capture: true
       }
-      return force;
-    }
-    if (isOpen) {
-      this.hidePopover();
-      return false;
-    }
-    this.showPopover();
-    return true;
-  };
+    });
+    (0, _bindEventListener.bind)(document, {
+      type: 'mouseup',
+      listener: pointerupAdapter,
+      options: {
+        capture: true
+      }
+    });
+    (0, _bindEventListener.bind)(document, {
+      type: 'keydown',
+      listener: handleDocumentKeydown,
+      options: {
+        capture: true
+      }
+    });
+  }
 }
 
 // ─── HTMLDialogElement ──────────────────────────────────────────────────────
+// Spec: https://html.spec.whatwg.org/multipage/interactive-elements.html#the-dialog-element
 
 if (typeof HTMLDialogElement !== 'undefined') {
   var proto = HTMLDialogElement.prototype;