@pine-ds/core 4.7.2 → 4.9.0

package/dist/collection/components/pds-popover/pds-popover.js

@@ -1,11 +1,35 @@
 import { Host, h } from "@stencil/core";
+import { autoUpdate, computePosition, flip, offset, platform, shift } from "@floating-ui/dom";
 import { closest, containsComposed } from "../../utils/closest";
 import { restoreReflectedDefault } from "../../utils/reflected-attribute-default";
 import { setAttributesIfChanged } from "../../utils/attributes";
 import { cssEscape } from "../../utils/css";
 import { limitRestores } from "../../utils/keep-hydrated";
-/** Open auto popovers, in the order they opened: Escape goes to the last one it applies to. */
-const openAutoPopovers = [];
+import { tabbableIn } from "../../utils/tabbable";
+/** Open popovers that close on Escape, in the order they opened: Escape goes to the last one it applies to. */
+const popoversTakingEscape = [];
+/** Hovering the trigger waits this long before opening, so a pointer passing over it doesn't open it. */
+const HOVER_OPEN_DELAY_MS = 120;
+/** Leaving the trigger and panel waits this long before closing, which covers the gap between them. */
+const HOVER_CLOSE_DELAY_MS = 200;
+/**
+ * floating-ui reporting viewport coordinates, as `position: fixed` uses without a containing block. Its own
+ * containing-block check misses a backdrop filter in WebKit, so handlePopoverPositioning corrects for one itself.
+ */
+const viewportPlatform = Object.assign(Object.assign({}, platform), { getOffsetParent: () => window });
+/**
+ * Where `top: 0; left: 0` puts a fixed element beside the given one. An empty probe is measured instead of the
+ * element, whose own transforms, such as an entrance animation, would otherwise read as part of the offset.
+ */
+const containingBlockOrigin = (element) => {
+    var _a;
+    const probe = document.createElement('div');
+    probe.style.cssText = 'all: initial; position: fixed; top: 0; left: 0;';
+    (_a = element.parentNode) === null || _a === void 0 ? void 0 : _a.insertBefore(probe, element);
+    const { top, left } = probe.getBoundingClientRect();
+    probe.remove();
+    return { top, left };
+};
 /** The focused element, followed down through shadow roots to the control that has focus. */
 function deepActiveElement() {
     var _a;
@@ -14,6 +38,27 @@ function deepActiveElement() {
         active = active.shadowRoot.activeElement;
     return active;
 }
+/** `node`, or the shadow host it sits in, lifted until it shares a tree with `other` or reaches the document. */
+function liftToTreeOf(node, other) {
+    let current = node;
+    while (current.getRootNode() !== other.getRootNode() && current.getRootNode() instanceof ShadowRoot) {
+        current = current.getRootNode().host;
+    }
+    return current;
+}
+/**
+ * Where `node` sits relative to `ref`, as `compareDocumentPosition` reports it. Whichever of the two
+ * is inside a shadow root is lifted to its host first, so a control inside a component compares too.
+ */
+function positionAcrossTrees(ref, node) {
+    const lifted = liftToTreeOf(node, ref);
+    return liftToTreeOf(ref, lifted).compareDocumentPosition(lifted);
+}
+const isPosition = (position, flag) => (position & Node.DOCUMENT_POSITION_DISCONNECTED) === 0 && (position & flag) !== 0;
+/** The popover each panel belongs to, so a popover inside another one's panel can find it. */
+const panelOwners = new WeakMap();
+/** Floating layers Pine components put at the end of the page or of a dialog, as a popover does its panel. */
+const FLOATING_LAYERS = '.pds-popover, .pds-datepicker-calendar-portal, .pds-combobox-dropdown-portal';
 /**
  * @slot trigger - The trigger element for the popover
  * @slot (default) - The content to display inside the popover
@@ -50,14 +95,21 @@ export class PdsPopover {
          */
         this.portalEl = null;
         /**
-         * Guard to prevent repositioning loops
+         * Stops floating-ui's autoUpdate, which repositions the open panel as its trigger or the page moves or resizes
+         */
+        this.stopAutoUpdate = null;
+        /**
+         * Counts positioning runs, so a run that resolves after a newer one started is dropped
+         */
+        this.positioningRun = 0;
+        /**
+         * The latest positioning run, which pdsPopoverOpen waits for so the panel's side is set when it fires
          */
-        this.isRepositioning = false;
+        this.positioning = Promise.resolve();
         /**
-         * Debounce timers for performance optimization
+         * Set while show() waits to emit pdsPopoverOpen, so a hide() in the meantime emits it first
          */
-        this.scrollDebounceTimer = null;
-        this.resizeDebounceTimer = null;
+        this.openEventPending = false;
         /**
          * Track moved nodes and their placeholders for restoration
          */
@@ -66,11 +118,41 @@ export class PdsPopover {
          * Timestamp when popover was opened (for preventing immediate close)
          */
         this.openTimestamp = 0;
+        /**
+         * Set while hover holds the popover open, until a click pins it or it closes
+         */
+        this.hoverOpened = false;
+        /**
+         * Set when the pointer left while focus was in the panel, so focus leaving it closes it instead
+         */
+        this.closeWhenFocusLeaves = false;
+        /**
+         * How far the pointer was from the panel at its last move after leaving the trigger
+         */
+        this.panelDistance = Infinity;
+        /**
+         * Stands in for the panel in the Tab order, right after the trigger, while the popover is open
+         */
+        this.tabGuardEl = null;
+        /**
+         * Set while focus passes through the guard on its way out of the panel
+         */
+        this.leavingPanel = false;
+        /**
+         * The direction of the Tab key being handled, until its default action has run
+         */
+        this.tabDirection = null;
         /**
          * Determines the action that triggers the popover. For manual popovers, the consumer is responsible for toggling this value.
          * @defaultValue "show"
          */
         this.popoverTargetAction = 'show';
+        /**
+         * Determines how the popover opens. With `hover`, it also opens when the pointer rests on the trigger and closes
+         * when the pointer leaves, until a click on the trigger keeps it open. Enter or Space on the trigger opens it either way.
+         * @defaultValue "click"
+         */
+        this.openOn = 'click';
         /**
          * Determines the type of popover. Auto popovers can be "light dismissed" by clicking outside of the popover.
          * Manual popovers require the consumer to handle the visibility of the popover.
@@ -81,6 +163,11 @@ export class PdsPopover {
          * @defaultValue 352
          */
         this.maxWidth = 352;
+        /**
+         * Sets the padding of the popover content
+         * @defaultValue "md"
+         */
+        this.padding = 'md';
         /**
          * Determines the preferred position of the popover
          * @defaultValue "right"
@@ -95,6 +182,7 @@ export class PdsPopover {
             // Clean up previous trigger's event listener if it exists
             if (this.triggerEl != null) {
                 this.triggerEl.removeEventListener('click', this.handleTriggerClick);
+                this.stopListeningForHover(this.triggerEl);
             }
             if (assignedElements.length > 0) {
                 // Use the first assigned element as the trigger
@@ -102,10 +190,14 @@ export class PdsPopover {
                 this.linkTriggerToPortal();
                 // Attach click listener to handle popover visibility
                 this.triggerEl.addEventListener('click', this.handleTriggerClick);
+                this.listenForHover(this.triggerEl);
             }
             else {
                 this.triggerEl = null;
             }
+            // autoUpdate watches the trigger it started with, so an open popover starts it again on the new one.
+            if (this.active)
+                this.addScrollAndResizeListeners();
             this.observeTrigger();
         };
         /**
@@ -128,6 +220,13 @@ export class PdsPopover {
             if (!anchorWithHref) {
                 event.preventDefault();
             }
+            if (this.openOn === 'hover' && this.popoverTargetAction !== 'hide') {
+                const heldByHover = this.hoverOpened;
+                this.pin();
+                // Pinning, not toggling: the hover before a click has already opened it.
+                if (heldByHover)
+                    return;
+            }
             // Execute the appropriate action based on popoverTargetAction prop
             switch (this.popoverTargetAction) {
                 case 'show':
@@ -142,6 +241,60 @@ export class PdsPopover {
                     break;
             }
         };
+        // A tap sends touch pointer events and then a click, so touch takes the click path alone.
+        this.handleHoverEnter = (event) => {
+            if (event.pointerType === 'touch')
+                return;
+            this.clearHoverTimers();
+            if (this.active)
+                return;
+            this.hoverOpenTimer = setTimeout(() => {
+                this.hoverOpenTimer = undefined;
+                if (this.active || this.portalEl == null)
+                    return;
+                this.hoverOpened = true;
+                this.show();
+            }, HOVER_OPEN_DELAY_MS);
+        };
+        this.handleHoverLeave = (event) => {
+            if (event.pointerType === 'touch')
+                return;
+            this.clearHoverTimers();
+            if (!this.hoverOpened)
+                return;
+            this.hoverCloseTimer = setTimeout(this.closeFromHover, HOVER_CLOSE_DELAY_MS);
+            if (event.currentTarget !== this.triggerEl)
+                return;
+            this.panelDistance = this.distanceToPanel(event);
+            document.addEventListener('pointermove', this.handleMoveTowardPanel);
+        };
+        // A slow diagonal from the trigger to a panel shorter than it runs beside the panel for longer
+        // than the close delay, so each move that brings the pointer closer starts the delay again.
+        this.handleMoveTowardPanel = (event) => {
+            const distance = this.distanceToPanel(event);
+            if (distance < this.panelDistance) {
+                clearTimeout(this.hoverCloseTimer);
+                this.hoverCloseTimer = setTimeout(this.closeFromHover, HOVER_CLOSE_DELAY_MS);
+            }
+            this.panelDistance = distance;
+        };
+        this.handleHoverFocusOut = (event) => {
+            if (!this.closeWhenFocusLeaves || containsComposed(this.portalEl, event.relatedTarget))
+                return;
+            this.closeWhenFocusLeaves = false;
+            this.hoverCloseTimer = setTimeout(this.closeFromHover, HOVER_CLOSE_DELAY_MS);
+        };
+        this.closeFromHover = () => {
+            this.clearHoverTimers();
+            if (!this.hoverOpened)
+                return;
+            // Content shown on hover stays while focus is in it (WCAG 1.4.13).
+            if (containsComposed(this.portalEl, deepActiveElement())) {
+                this.closeWhenFocusLeaves = true;
+                return;
+            }
+            this.hide();
+        };
         /** The focus style copied into a shadow root the panel opened in, which `document.head` can't reach. */
         this.shadowFocusStyle = null;
         /** The dialog the panel was opened in, closed along with it. */
@@ -162,6 +315,85 @@ export class PdsPopover {
                 event.stopPropagation();
             }
         };
+        // At the end of the body or of a dialog, the panel would come last in the Tab order. The guard
+        // after the trigger takes its place there, while the panel has a control for it to lead to.
+        this.syncTabGuard = (event) => {
+            if (event.key !== 'Tab')
+                return;
+            this.releasePanel();
+            this.tabDirection = event.shiftKey ? 'backward' : 'forward';
+            setTimeout(this.endTabKey);
+            // Read on each Tab, as the panel's content can arrive after it opens.
+            const guarding = this.guardedTabbables().length > 0;
+            if (this.tabGuardEl != null)
+                this.tabGuardEl.tabIndex = guarding ? 0 : -1;
+            // Inert for this key press, the panel is reached only through the guard, either way round. A
+            // control in another floating layer, such as a nested popover's panel, may move focus back into it.
+            const focused = deepActiveElement();
+            if (guarding && !containsComposed(this.portalEl, focused) && !closest(FLOATING_LAYERS, focused !== null && focused !== void 0 ? focused : document)) {
+                this.portalEl.inert = true;
+            }
+        };
+        this.endTabKey = () => {
+            this.tabDirection = null;
+            this.releasePanel();
+        };
+        this.handleTabGuardFocus = (event) => {
+            if (this.leavingPanel)
+                return;
+            // An inert panel's controls aren't tabbable, so the guard would find none to send focus to.
+            this.releasePanel();
+            const tabbables = this.guardedTabbables();
+            // A Tab press says which end of the panel focus comes in at; without one, where it came from does.
+            const from = event.relatedTarget;
+            const backward = this.tabDirection != null ? this.tabDirection === 'backward' : from != null && this.isAfterPopover(from);
+            const target = backward ? tabbables[tabbables.length - 1] : tabbables[0];
+            // Focus can reach the guard without a Tab keydown here (from a frame, or assistive tech) after
+            // the panel's controls are gone. The trigger is the nearest visible place for it.
+            if (target == null)
+                this.returnFocusToTrigger();
+            else
+                target.focus();
+        };
+        this.handleTabFromPanel = (event) => {
+            if (event.key !== 'Tab' || event.defaultPrevented || this.tabGuardEl == null)
+                return;
+            const tabbables = this.guardedTabbables();
+            const edge = event.shiftKey ? tabbables[0] : tabbables[tabbables.length - 1];
+            if (edge == null || deepActiveElement() !== edge)
+                return;
+            this.leavePanel(edge, event.shiftKey);
+        };
+        this.releasePanel = () => {
+            if (this.portalEl != null)
+                this.portalEl.inert = false;
+        };
+    }
+    openOnChanged() {
+        this.pin();
+        this.stopListeningForHover(this.triggerEl);
+        this.stopListeningForHover(this.portalEl);
+        // Out of the page, connectedCallback binds them when it comes back.
+        if (!this.isComponentMounted)
+            return;
+        this.listenForHover(this.triggerEl);
+        this.listenForHover(this.portalEl);
+    }
+    applyPadding() {
+        if (this.portalEl != null)
+            this.portalEl.style.padding = this.paddingToken();
+    }
+    paddingToken() {
+        switch (this.padding) {
+            case 'none':
+                return 'var(--pine-dimension-none)';
+            case 'xs':
+                return 'var(--pine-dimension-xs)';
+            case 'sm':
+                return 'var(--pine-dimension-sm)';
+            default:
+                return 'var(--pine-dimension-md)';
+        }
     }
     restorePlacementDefault(newValue) {
         this.placement = restoreReflectedDefault(this.el, 'placement', newValue, 'right');
@@ -171,8 +403,6 @@ export class PdsPopover {
         // Bind event handlers for cleanup
         this.boundClickOutsideHandler = this.handleClickOutside.bind(this);
         this.boundEscapeKeyHandler = this.handleEscapeKey.bind(this);
-        this.boundScrollHandler = this.handleScroll.bind(this);
-        this.boundResizeHandler = this.handleResize.bind(this);
         // Create portal element
         this.createPortal();
         this.hasLoaded = true;
@@ -213,6 +443,48 @@ export class PdsPopover {
         // Skips values already in place, so the trigger observer's own callback doesn't loop.
         return setAttributesIfChanged(this.triggerEl, { 'aria-expanded': String(this.active), 'aria-controls': this.portalEl.id });
     }
+    listenForHover(el) {
+        if (this.openOn !== 'hover' || el == null)
+            return;
+        el.addEventListener('pointerenter', this.handleHoverEnter);
+        el.addEventListener('pointerleave', this.handleHoverLeave);
+        el.addEventListener('focusout', this.handleHoverFocusOut);
+    }
+    stopListeningForHover(el) {
+        if (el == null)
+            return;
+        el.removeEventListener('pointerenter', this.handleHoverEnter);
+        el.removeEventListener('pointerleave', this.handleHoverLeave);
+        el.removeEventListener('focusout', this.handleHoverFocusOut);
+    }
+    distanceToPanel({ clientX, clientY }) {
+        const panel = this.portalEl.getBoundingClientRect();
+        return Math.hypot(Math.max(panel.left - clientX, 0, clientX - panel.right), Math.max(panel.top - clientY, 0, clientY - panel.bottom));
+    }
+    /**
+     * Keeps a popover that hover opened open, closing from then on as one opened by a click does. A
+     * manual one gives up Escape again, which it took only while hover held it.
+     */
+    pin() {
+        var _a;
+        this.clearHoverTimers();
+        if (!this.hoverOpened)
+            return;
+        this.hoverOpened = false;
+        if (this.popoverType === 'auto')
+            return;
+        this.forgetOpen();
+        (_a = this.portalEl) === null || _a === void 0 ? void 0 : _a.removeAttribute('data-pds-popover-open');
+        document.removeEventListener('keydown', this.boundEscapeKeyHandler);
+    }
+    clearHoverTimers() {
+        clearTimeout(this.hoverOpenTimer);
+        clearTimeout(this.hoverCloseTimer);
+        this.hoverOpenTimer = undefined;
+        this.hoverCloseTimer = undefined;
+        this.closeWhenFocusLeaves = false;
+        document.removeEventListener('pointermove', this.handleMoveTowardPanel);
+    }
     // componentDidLoad doesn't run again when a popover comes back, so rebuild whatever
     // disconnectedCallback tore down. Each step is a no-op when nothing was.
     connectedCallback() {
@@ -222,17 +494,19 @@ export class PdsPopover {
         this.isComponentMounted = true;
         this.createPortal();
         (_a = this.triggerEl) === null || _a === void 0 ? void 0 : _a.addEventListener('click', this.handleTriggerClick);
+        this.listenForHover(this.triggerEl);
         this.observeTrigger();
         this.linkTriggerToPortal();
         // Still open after a move: the trigger moved, so the portal follows it, into the dialog it
         // is in now, if any.
         if (this.active) {
             this.placePortal();
-            requestAnimationFrame(() => this.handlePopoverPositioning());
+            // autoUpdate listens to the scroll containers around where the trigger was, so it starts again.
+            this.addScrollAndResizeListeners();
         }
     }
     disconnectedCallback() {
-        var _a;
+        var _a, _b;
         // Moved in one operation (a DOM morph, or a framework reparenting it), the popover is
         // already back in the page. Its portal is outside the popover, so it stays open, with focus
         // where it was; connectedCallback moves it to follow the popover.
@@ -247,6 +521,7 @@ export class PdsPopover {
             this.restorePortalContent();
             this.active = false;
             this.linkTriggerToPortal();
+            this.emitOpenEvent();
             this.pdsPopoverClose.emit({
                 componentId: this.componentId,
                 popoverType: this.popoverType,
@@ -256,36 +531,27 @@ export class PdsPopover {
         if (this.triggerEl != null) {
             this.triggerEl.removeEventListener('click', this.handleTriggerClick);
         }
+        this.stopListeningForHover(this.triggerEl);
         (_a = this.triggerObserver) === null || _a === void 0 ? void 0 : _a.disconnect();
         this.triggerObserver = null;
         // Clean up all event listeners
         this.removeLightDismissListeners();
         this.removeScrollAndResizeListeners();
         document.removeEventListener('submit', this.handleSubmitFromPanel, true);
-        // Clear any pending debounce timers
-        this.clearDebounceTimers();
+        document.removeEventListener('keydown', this.syncTabGuard, true);
+        (_b = this.tabGuardEl) === null || _b === void 0 ? void 0 : _b.removeAttribute('tabindex');
+        this.clearHoverTimers();
+        this.hoverOpened = false;
         // Remove portal from DOM
         this.removePortal();
     }
-    /**
-     * Clears any pending debounce timers
-     */
-    clearDebounceTimers() {
-        if (this.scrollDebounceTimer !== null) {
-            clearTimeout(this.scrollDebounceTimer);
-            this.scrollDebounceTimer = null;
-        }
-        if (this.resizeDebounceTimer !== null) {
-            clearTimeout(this.resizeDebounceTimer);
-            this.resizeDebounceTimer = null;
-        }
-    }
     createPortal() {
         var _a;
         if (this.portalEl !== null)
             return;
         this.portalEl = document.createElement('div');
         this.portalEl.className = 'pds-popover';
+        panelOwners.set(this.portalEl, this);
         // Apply all styles inline since portal is outside shadow DOM
         this.portalEl.style.position = 'fixed';
         this.portalEl.style.zIndex = 'var(--pine-z-index-raised)';
@@ -297,7 +563,7 @@ export class PdsPopover {
         this.portalEl.style.borderRadius = 'var(--pine-dimension-125)';
         this.portalEl.style.boxShadow = 'var(--pine-box-shadow-200)';
         this.portalEl.style.margin = 'var(--pine-dimension-none)';
-        this.portalEl.style.padding = 'var(--pine-dimension-md)';
+        this.portalEl.style.padding = this.paddingToken();
         // Generate unique ID
         if (!this.componentId) {
             (_a = this.generatedPortalId) !== null && _a !== void 0 ? _a : (this.generatedPortalId = `pds-popover-portal-${PdsPopover.instanceCounter++}`);
@@ -311,6 +577,8 @@ export class PdsPopover {
         // Add global focus styles to match Pine design system
         // This is done after appending to ensure it's part of the document and can access CSS variables
         this.addPortalFocusStyles();
+        this.listenForHover(this.portalEl);
+        this.portalEl.addEventListener('keydown', this.handleTabFromPanel);
     }
     /**
      * Adds Pine design system focus styles and dark mode border to the portal element
@@ -438,27 +706,40 @@ export class PdsPopover {
         // Update portal content with latest slot content
         this.updatePortalContent();
         // Show portal. The attribute tells a modal around it that this popover takes Escape first; only
-        // an auto popover listens for Escape.
-        if (this.popoverType === 'auto')
+        // an auto popover, or one hover opened, listens for Escape.
+        if (this.popoverType === 'auto' || this.hoverOpened)
             this.portalEl.setAttribute('data-pds-popover-open', '');
         this.portalEl.style.display = 'block';
         this.portalEl.style.opacity = '1';
         this.portalEl.style.visibility = 'visible';
-        // Position the popover
-        requestAnimationFrame(() => {
-            if (!this.isComponentMounted)
-                return;
-            this.handlePopoverPositioning();
-        });
-        // Add scroll and resize listeners for repositioning (always)
+        // Position the popover now, and again whenever its trigger or the page moves or resizes
         this.addScrollAndResizeListeners();
         document.addEventListener('submit', this.handleSubmitFromPanel, true);
-        // Add document listeners for light dismiss and escape key (auto type only)
+        document.addEventListener('keydown', this.syncTabGuard, true);
+        // Add document listeners for light dismiss and escape key (auto type only), or for the escape
+        // key alone while hover holds a manual popover open
         if (this.popoverType === 'auto') {
-            openAutoPopovers.push(this);
+            popoversTakingEscape.push(this);
             this.addLightDismissListeners();
         }
-        // Emit open event
+        else if (this.hoverOpened) {
+            popoversTakingEscape.push(this);
+            document.addEventListener('keydown', this.boundEscapeKeyHandler);
+        }
+        // Emit open event once the panel is positioned, with the side it took already on it. A reconnect, a
+        // trigger swap or another show() can start a newer run meanwhile, which drops this one, so wait for the latest.
+        this.openEventPending = true;
+        let positioning;
+        do {
+            positioning = this.positioning;
+            await positioning;
+        } while (positioning !== this.positioning);
+        this.emitOpenEvent();
+    }
+    emitOpenEvent() {
+        if (!this.openEventPending)
+            return;
+        this.openEventPending = false;
         this.pdsPopoverOpen.emit({
             componentId: this.componentId,
             popoverType: this.popoverType,
@@ -468,9 +749,12 @@ export class PdsPopover {
      * Closes the popover programmatically
      */
     async hide() {
+        var _a;
+        this.clearHoverTimers();
         if (!this.active || !this.portalEl)
             return;
         this.active = false;
+        this.hoverOpened = false;
         this.unwatchDialogClose();
         // Restoring the content drops its focus to the body, so check where focus is first. In a
         // shadow root, document.activeElement is only its host.
@@ -481,6 +765,7 @@ export class PdsPopover {
         // Hide portal. The dark-mode border set in a shadow root is worked out again on the next open.
         this.portalEl.style.border = '';
         this.portalEl.removeAttribute('data-pds-popover-open');
+        this.portalEl.removeAttribute('data-pds-popover-placement');
         this.portalEl.style.display = 'none';
         this.portalEl.style.opacity = '0';
         this.portalEl.style.visibility = 'hidden';
@@ -494,8 +779,11 @@ export class PdsPopover {
         this.removeLightDismissListeners();
         this.removeScrollAndResizeListeners();
         document.removeEventListener('submit', this.handleSubmitFromPanel, true);
-        // Clear any pending timers
-        this.clearDebounceTimers();
+        document.removeEventListener('keydown', this.syncTabGuard, true);
+        (_a = this.tabGuardEl) === null || _a === void 0 ? void 0 : _a.removeAttribute('tabindex');
+        this.releasePanel();
+        // Closed before its first position resolved, it still announces the open before the close.
+        this.emitOpenEvent();
         // Emit close event
         this.pdsPopoverClose.emit({
             componentId: this.componentId,
@@ -507,10 +795,10 @@ export class PdsPopover {
      */
     async toggle() {
         if (this.active) {
-            this.hide();
+            await this.hide();
         }
         else {
-            this.show();
+            await this.show();
         }
     }
     /**
@@ -549,9 +837,9 @@ export class PdsPopover {
         this.portalEl.style.border = root instanceof ShadowRoot && closest('[data-theme="dark"]', this.el) ? 'var(--pine-border)' : '';
     }
     forgetOpen() {
-        const index = openAutoPopovers.indexOf(this);
+        const index = popoversTakingEscape.indexOf(this);
         if (index >= 0)
-            openAutoPopovers.splice(index, 1);
+            popoversTakingEscape.splice(index, 1);
     }
     /**
      * Whether an Escape is this popover's. One from a dialog the popover isn't in belongs to that
@@ -594,19 +882,62 @@ export class PdsPopover {
         document.removeEventListener('click', this.boundClickOutsideHandler, true);
         document.removeEventListener('keydown', this.boundEscapeKeyHandler);
     }
+    /**
+     * The panel's controls that Tab reaches through the guard. None when the panel sits right after
+     * the popover, in a dialog, where it's already next in the Tab order.
+     */
+    guardedTabbables() {
+        if (this.portalEl == null || this.el.nextElementSibling === this.portalEl)
+            return [];
+        return tabbableIn(this.portalEl);
+    }
+    isAfterPopover(node) {
+        if (containsComposed(this.el, node))
+            return false;
+        return isPosition(positionAcrossTrees(this.el, node), Node.DOCUMENT_POSITION_FOLLOWING);
+    }
+    /**
+     * Moves focus to the guard without preventing the Tab, so the browser's Tab carries on from there.
+     * Inert until then, the panel can't be where it lands.
+     */
+    leavePanel(edge, backward) {
+        var _a, _b;
+        this.leavingPanel = true;
+        (_a = this.tabGuardEl) === null || _a === void 0 ? void 0 : _a.focus();
+        this.leavingPanel = false;
+        this.portalEl.inert = true;
+        setTimeout(() => this.finishLeavingPanel(edge));
+        // Last in another popover's panel, the guard hands the Tab on to that popover's own guard.
+        const outer = panelOwners.get(closest('.pds-popover', this.el));
+        const outerTabbables = (_b = outer === null || outer === void 0 ? void 0 : outer.guardedTabbables()) !== null && _b !== void 0 ? _b : [];
+        if (!backward && outerTabbables[outerTabbables.length - 1] === this.tabGuardEl)
+            outer.leavePanel(edge, false);
+    }
+    // With nowhere for the browser's Tab to go, focus would stay on the invisible guard.
+    finishLeavingPanel(edge) {
+        var _a;
+        this.releasePanel();
+        if (this.active && ((_a = this.el.shadowRoot) === null || _a === void 0 ? void 0 : _a.activeElement) === this.tabGuardEl)
+            edge.focus();
+    }
     /**
      * Adds scroll and resize listeners for repositioning
      */
     addScrollAndResizeListeners() {
-        window.addEventListener('scroll', this.boundScrollHandler, true);
-        window.addEventListener('resize', this.boundResizeHandler);
+        this.removeScrollAndResizeListeners();
+        if (this.triggerEl == null || this.portalEl == null)
+            return;
+        this.stopAutoUpdate = autoUpdate(this.triggerEl, this.portalEl, () => {
+            this.positioning = this.handlePopoverPositioning().catch(error => console.warn('pds-popover: failed to position the panel', error));
+        });
     }
     /**
      * Removes scroll and resize listeners
      */
     removeScrollAndResizeListeners() {
-        window.removeEventListener('scroll', this.boundScrollHandler, true);
-        window.removeEventListener('resize', this.boundResizeHandler);
+        var _a;
+        (_a = this.stopAutoUpdate) === null || _a === void 0 ? void 0 : _a.call(this);
+        this.stopAutoUpdate = null;
     }
     /**
      * Handles clicks outside the popover for light dismiss (auto type only)
@@ -660,7 +991,7 @@ export class PdsPopover {
             return;
         // Like the native Popover API, Escape closes only the top popover: the last one opened that
         // it applies to. Every open popover hears it, so each checks whether it's that one.
-        const top = [...openAutoPopovers].reverse().find(popover => popover.takesEscapeFrom(event));
+        const top = [...popoversTakingEscape].reverse().find(popover => popover.takesEscapeFrom(event));
         if (top !== this)
             return;
         // Take the key, so the dialog or modal around it doesn't close too.
@@ -670,122 +1001,38 @@ export class PdsPopover {
         this.hide();
     }
     /**
-     * Handles scroll events to reposition the popover (debounced for performance)
+     * Positions the popover relative to its trigger element, flipping to the opposite side when only that side has
+     * room and shifting to stay 8px inside the viewport. The side it takes goes on the panel's `data-pds-popover-placement`.
      */
-    handleScroll() {
-        if (!this.active)
-            return;
-        if (this.scrollDebounceTimer !== null) {
-            clearTimeout(this.scrollDebounceTimer);
-        }
-        this.scrollDebounceTimer = setTimeout(() => {
-            this.handlePopoverPositioning();
-            this.scrollDebounceTimer = null;
-        }, 10); // 10ms debounce for smooth repositioning
-    }
-    /**
-     * Handles resize events to reposition the popover (debounced for performance)
-     */
-    handleResize() {
-        if (!this.active)
-            return;
-        if (this.resizeDebounceTimer !== null) {
-            clearTimeout(this.resizeDebounceTimer);
-        }
-        this.resizeDebounceTimer = setTimeout(() => {
-            this.handlePopoverPositioning();
-            this.resizeDebounceTimer = null;
-        }, 100); // 100ms debounce for resize
-    }
-    /**
-     * Positions the popover relative to its trigger element
-     */
-    handlePopoverPositioning() {
-        // Prevent repositioning loops
-        if (this.isRepositioning) {
-            return;
-        }
-        this.isRepositioning = true;
-        if (this.triggerEl == null || this.portalEl == null) {
-            this.isRepositioning = false;
+    async handlePopoverPositioning() {
+        // Counted before the guards, so a run still in flight is dropped even when this one can't position.
+        const run = ++this.positioningRun;
+        if (this.triggerEl == null || this.portalEl == null)
             return;
-        }
-        const triggerRect = this.triggerEl.getBoundingClientRect();
-        const popoverRect = this.portalEl.getBoundingClientRect();
         // Safety check: ensure trigger has valid dimensions (is rendered and visible)
-        if (triggerRect.width === 0 || triggerRect.height === 0) {
-            this.isRepositioning = false;
+        const triggerRect = this.triggerEl.getBoundingClientRect();
+        if (triggerRect.width === 0 || triggerRect.height === 0)
             return;
-        }
-        let top = 0;
-        let left = 0;
-        const offset = 8;
-        switch (this.placement) {
-            case 'top':
-                top = triggerRect.top - popoverRect.height - offset;
-                left = triggerRect.left + (triggerRect.width - popoverRect.width) / 2;
-                break;
-            case 'top-start':
-                top = triggerRect.top - popoverRect.height - offset;
-                left = triggerRect.left;
-                break;
-            case 'top-end':
-                top = triggerRect.top - popoverRect.height - offset;
-                left = triggerRect.right - popoverRect.width;
-                break;
-            case 'right':
-                top = triggerRect.top + (triggerRect.height - popoverRect.height) / 2;
-                left = triggerRect.right + offset;
-                break;
-            case 'right-start':
-                top = triggerRect.top;
-                left = triggerRect.right + offset;
-                break;
-            case 'right-end':
-                top = triggerRect.bottom - popoverRect.height;
-                left = triggerRect.right + offset;
-                break;
-            case 'bottom':
-                top = triggerRect.bottom + offset;
-                left = triggerRect.left + (triggerRect.width - popoverRect.width) / 2;
-                break;
-            case 'bottom-start':
-                top = triggerRect.bottom + offset;
-                left = triggerRect.left;
-                break;
-            case 'bottom-end':
-                top = triggerRect.bottom + offset;
-                left = triggerRect.right - popoverRect.width;
-                break;
-            case 'left':
-                top = triggerRect.top + (triggerRect.height - popoverRect.height) / 2;
-                left = triggerRect.left - popoverRect.width - offset;
-                break;
-            case 'left-start':
-                top = triggerRect.top;
-                left = triggerRect.left - popoverRect.width - offset;
-                break;
-            case 'left-end':
-                top = triggerRect.bottom - popoverRect.height;
-                left = triggerRect.left - popoverRect.width - offset;
-                break;
-        }
-        this.portalEl.style.top = `${top}px`;
-        this.portalEl.style.left = `${left}px`;
+        const portal = this.portalEl;
+        const { x: left, y: top, placement } = await computePosition(this.triggerEl, portal, {
+            placement: this.placement,
+            strategy: 'fixed',
+            // With no room on either side, stay on the preferred side: the side that overflows less can still push
+            // a tall panel's start above the viewport.
+            middleware: [offset(8), flip({ fallbackStrategy: 'initialPlacement' }), shift({ padding: 8 })],
+            platform: viewportPlatform,
+        });
+        if (!this.active || run !== this.positioningRun || portal !== this.portalEl)
+            return;
+        portal.setAttribute('data-pds-popover-placement', placement);
         // `position: fixed` measures from the viewport unless an ancestor becomes its containing block,
-        // as a modal dialog does with its backdrop filter. Shift by however far it landed from the spot.
-        const placed = this.portalEl.getBoundingClientRect();
-        if (Math.abs(placed.top - top) > 0.5 || Math.abs(placed.left - left) > 0.5) {
-            this.portalEl.style.top = `${2 * top - placed.top}px`;
-            this.portalEl.style.left = `${2 * left - placed.left}px`;
-        }
-        // Reset the repositioning guard after a short delay
-        setTimeout(() => {
-            this.isRepositioning = false;
-        }, 16); // ~1 frame at 60fps
+        // as a modal dialog does with its backdrop filter. Offset by however far that block's corner is from the viewport's.
+        const origin = containingBlockOrigin(portal);
+        portal.style.top = `${top - origin.top}px`;
+        portal.style.left = `${left - origin.left}px`;
     }
     render() {
-        return (h(Host, { key: 'da8a0c715df1199231b1265085f3f9ae0234032d', id: this.componentId }, h("span", { key: 'f35023492399420829cec2e88556462f5ac1663e', class: "pds-popover__trigger-wrapper" }, h("slot", { key: '38ebe92eebb87665467b3f92ff94dc8095450063', name: "trigger", onSlotchange: this.handleTriggerSlotChange })), h("div", { key: '8917930f4520544d14bbd68b4c7936dd60af19e3', class: "pds-popover__content-slot-wrapper" }, h("slot", { key: '28d3f9112256edd95721a79a7072a9e35a3712bf', onSlotchange: this.handleContentSlotChange }))));
+        return (h(Host, { key: '85422eb7544a4795ce78b51684b7224a5d856a4e', id: this.componentId }, h("span", { key: '6fe9c827ed4d46ca723d6013f296faf80ba31366', class: "pds-popover__trigger-wrapper" }, h("slot", { key: '970d1974d2be1451e670a36e7d2ccdc5979595bb', name: "trigger", onSlotchange: this.handleTriggerSlotChange })), h("span", { key: '0c76f76286a30d8e6e948bd0abab3317b3673aa6', class: "pds-popover__tab-guard", ref: (el) => (this.tabGuardEl = el !== null && el !== void 0 ? el : null), onFocus: this.handleTabGuardFocus }), h("div", { key: '692c45e93899e74a3d5970f3a3625f6115ab63b0', class: "pds-popover__content-slot-wrapper" }, h("slot", { key: 'f1566e0eb1eb08626f2a8285447702ce96b09f4d', onSlotchange: this.handleContentSlotChange }))));
     }
     static get is() { return "pds-popover"; }
     static get encapsulation() { return "shadow"; }
@@ -824,6 +1071,29 @@ export class PdsPopover {
                 "attribute": "popover-target-action",
                 "defaultValue": "'show'"
             },
+            "openOn": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'click' | 'hover'",
+                    "resolved": "\"click\" | \"hover\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "defaultValue",
+                            "text": "\"click\""
+                        }],
+                    "text": "Determines how the popover opens. With `hover`, it also opens when the pointer rests on the trigger and closes\nwhen the pointer leaves, until a click on the trigger keeps it open. Enter or Space on the trigger opens it either way."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "open-on",
+                "defaultValue": "'click'"
+            },
             "popoverType": {
                 "type": "string",
                 "mutable": false,
@@ -886,6 +1156,36 @@ export class PdsPopover {
                 "attribute": "max-width",
                 "defaultValue": "352"
             },
+            "padding": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "PopoverPaddingType",
+                    "resolved": "\"md\" | \"none\" | \"sm\" | \"xs\"",
+                    "references": {
+                        "PopoverPaddingType": {
+                            "location": "import",
+                            "path": "@utils/types",
+                            "id": "src/utils/types.ts::PopoverPaddingType",
+                            "referenceLocation": "PopoverPaddingType"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "defaultValue",
+                            "text": "\"md\""
+                        }],
+                    "text": "Sets the padding of the popover content"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "padding",
+                "defaultValue": "'md'"
+            },
             "placement": {
                 "type": "string",
                 "mutable": true,
@@ -1028,6 +1328,12 @@ export class PdsPopover {
     static get elementRef() { return "el"; }
     static get watchers() {
         return [{
+                "propName": "openOn",
+                "methodName": "openOnChanged"
+            }, {
+                "propName": "padding",
+                "methodName": "applyPadding"
+            }, {
                 "propName": "placement",
                 "methodName": "restorePlacementDefault"
             }];