@pine-ds/core 4.6.0 → 4.7.1

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

@@ -1,20 +1,22 @@
 import { Host, h } from "@stencil/core";
 import { closest, containsComposed } from "../../utils/closest";
 import { unwrapReconnectedContent } from "../../utils/reconnected-content";
-// Known selectors for content Pine components portal to document.body rather
-// than rendering in place — pds-popover, pds-tooltip, pds-combobox's dropdown.
+// Known selectors for content Pine components portal out of place rather than
+// rendering where they are — pds-tooltip and pds-combobox's dropdown in
+// document.body, pds-popover in the body or the open dialog it's in.
 // A pointerdown landing on one of these is not "outside" the drawer in the
 // sense light dismiss cares about: it belongs to an overlay something inside
 // the drawer opened, even though it is not a DOM descendant of the drawer.
 const PORTALED_OVERLAY_SELECTOR = '.pds-popover, .pds-tooltip, .pds-combobox-dropdown-portal';
 /**
- * A non-modal side panel composed from `pds-modal`.
+ * A side panel composed from `pds-modal`, non-modal by default.
  *
- * Unlike `pds-modal`, the page stays interactive while a drawer is open: no
- * dimming, no blur, no scroll lock, no click blocking. `pds-drawer` renders a
- * `pds-modal` internally with `disableTopLayer` always on and its backdrop
- * suppressed, and adds the edge, width and dismiss behavior a side panel
- * needs on top. It does not reimplement focus, Escape or dialog semantics —
+ * By default, unlike `pds-modal`, the page stays interactive while a drawer
+ * is open: no dimming, no blur, no scroll lock, no click blocking.
+ * `pds-drawer` renders a `pds-modal` internally with `disableTopLayer` on and
+ * its backdrop suppressed, and adds the edge, width and dismiss behavior a
+ * side panel needs on top. With `modal`, it opens that `pds-modal` in the top
+ * layer instead and keeps its backdrop. It does not reimplement focus, Escape or dialog semantics —
  * those come from `pds-modal` unchanged.
  * @lightDom renders-markup
  */
@@ -42,8 +44,18 @@ export class PdsDrawer {
          */
         this.scrollable = true;
         /**
-         * Whether the drawer can be dismissed with a pointerdown outside it.
-         * Replaces `pds-modal`'s `backdropDismiss` — there is no backdrop to click.
+         * Whether the drawer is modal. A modal drawer dims the page behind it with a
+         * backdrop, makes the page inert, and keeps focus inside the drawer, like
+         * `pds-modal`. Use it for a task the page should wait on. Leave it off for a
+         * panel people work alongside the page. Read when the drawer opens; changing
+         * it while the drawer is open is not supported.
+         * @default false
+         */
+        this.modal = false;
+        /**
+         * Whether the drawer can be dismissed with a pointerdown outside it (in a
+         * `modal` drawer, a click on its backdrop).
+         * Replaces `pds-modal`'s `backdropDismiss`.
          * This also gates Escape, matching how `backdropDismiss` gates Escape on
          * `pds-modal` today: setting this to `false` means the close button is the
          * only way out.
@@ -62,7 +74,8 @@ export class PdsDrawer {
          * background event while the user is mid-task elsewhere on the page —
          * moving focus there would interrupt them, and the page stays live under
          * a non-modal drawer, so it is a genuine data-entry risk, not just an
-         * annoyance.
+         * annoyance. A `modal` drawer ignores `none`: the page behind it is inert,
+         * so focus starts in the drawer.
          * @default 'auto'
          */
         this.initialFocus = 'auto';
@@ -108,7 +121,8 @@ export class PdsDrawer {
     // page underneath stays genuinely clickable, which means a click there
     // never reaches pds-modal's backdrop element at all.
     handleOutsidePointerDown(e) {
-        if (!this.lightDismiss || !this.open)
+        // A modal drawer's backdrop takes the click instead, through pds-modal.
+        if (this.modal || !this.lightDismiss || !this.open)
             return;
         const target = e.target;
         if (!target)
@@ -118,7 +132,7 @@ export class PdsDrawer {
         if (target.closest(PORTALED_OVERLAY_SELECTOR))
             return;
         // A datepicker's portaled calendar counts as inside only when its datepicker is in the drawer,
-        // or in an overlay portaled from it (a pds-popover in the drawer puts its content on the body).
+        // or in an overlay portaled from it (a pds-popover in the drawer puts its content beside it).
         const calendar = target.closest('.pds-datepicker-calendar-portal');
         const owner = calendar === null || calendar === void 0 ? void 0 : calendar.pdsDatepicker;
         if (owner && (containsComposed(this.el, owner) || closest(PORTALED_OVERLAY_SELECTOR, owner)))
@@ -134,11 +148,11 @@ export class PdsDrawer {
         this.open = false;
     }
     render() {
-        return (h(Host, { key: 'ae7e67ed196ef95a39c2b729e859712ce5c41144', class: {
+        return (h(Host, { key: '287bf043c991209488eb1b617031acffb59ff9af', class: {
                 'pds-drawer': true,
                 [`pds-drawer--${this.side}`]: true,
                 [`pds-drawer--${this.size}`]: true,
-            } }, h("pds-modal", { key: '9b35ce377c84612a844a561d5540e98b08c0e499', class: "pds-drawer__modal", ref: (el) => (this.modalEl = el), componentId: this.componentId, open: this.open, scrollable: this.scrollable, disableTopLayer: true, backdropDismiss: this.lightDismiss, disableInitialFocus: this.initialFocus === 'none' }, h("slot", { key: 'dda01aa40dc41b3d17073238a8cad8d816571e18' }))));
+            } }, h("pds-modal", { key: 'cd86fb552353f5cc12fb36fc956033432a91847c', class: { 'pds-drawer__modal': true, 'pds-drawer__modal--modal': this.modal }, ref: (el) => (this.modalEl = el), componentId: this.componentId, open: this.open, scrollable: this.scrollable, disableTopLayer: !this.modal, backdropDismiss: this.lightDismiss, disableInitialFocus: !this.modal && this.initialFocus === 'none' }, h("slot", { key: '56bbe9b5c26b10b07c0f503ba147899a57a5de85' }))));
     }
     static get is() { return "pds-drawer"; }
     static get originalStyleUrls() {
@@ -264,6 +278,29 @@ export class PdsDrawer {
                 "attribute": "scrollable",
                 "defaultValue": "true"
             },
+            "modal": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "Whether the drawer is modal. A modal drawer dims the page behind it with a\nbackdrop, makes the page inert, and keeps focus inside the drawer, like\n`pds-modal`. Use it for a task the page should wait on. Leave it off for a\npanel people work alongside the page. Read when the drawer opens; changing\nit while the drawer is open is not supported."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "modal",
+                "defaultValue": "false"
+            },
             "lightDismiss": {
                 "type": "boolean",
                 "mutable": false,
@@ -279,7 +316,7 @@ export class PdsDrawer {
                             "name": "default",
                             "text": "true"
                         }],
-                    "text": "Whether the drawer can be dismissed with a pointerdown outside it.\nReplaces `pds-modal`'s `backdropDismiss` \u2014 there is no backdrop to click.\nThis also gates Escape, matching how `backdropDismiss` gates Escape on\n`pds-modal` today: setting this to `false` means the close button is the\nonly way out.\n\nA trigger outside the drawer should only ever set `open` to `true` and\nleave closing to the drawer itself. A toggle-style trigger (`open =\n!open`) fights light dismiss: clicking it while open closes the drawer\non `pointerdown`, then the trigger's own click handler re-opens it."
+                    "text": "Whether the drawer can be dismissed with a pointerdown outside it (in a\n`modal` drawer, a click on its backdrop).\nReplaces `pds-modal`'s `backdropDismiss`.\nThis also gates Escape, matching how `backdropDismiss` gates Escape on\n`pds-modal` today: setting this to `false` means the close button is the\nonly way out.\n\nA trigger outside the drawer should only ever set `open` to `true` and\nleave closing to the drawer itself. A toggle-style trigger (`open =\n!open`) fights light dismiss: clicking it while open closes the drawer\non `pointerdown`, then the trigger's own click handler re-opens it."
                 },
                 "getter": false,
                 "setter": false,
@@ -302,7 +339,7 @@ export class PdsDrawer {
                             "name": "default",
                             "text": "'auto'"
                         }],
-                    "text": "Whether to move focus into the drawer when it opens. `auto` is right for\na drawer opened by a direct user action (a click, a deep link the user\njust navigated to). Set to `none` for a drawer that can open from a\nbackground event while the user is mid-task elsewhere on the page \u2014\nmoving focus there would interrupt them, and the page stays live under\na non-modal drawer, so it is a genuine data-entry risk, not just an\nannoyance."
+                    "text": "Whether to move focus into the drawer when it opens. `auto` is right for\na drawer opened by a direct user action (a click, a deep link the user\njust navigated to). Set to `none` for a drawer that can open from a\nbackground event while the user is mid-task elsewhere on the page \u2014\nmoving focus there would interrupt them, and the page stays live under\na non-modal drawer, so it is a genuine data-entry risk, not just an\nannoyance. A `modal` drawer ignores `none`: the page behind it is inert,\nso focus starts in the drawer."
                 },
                 "getter": false,
                 "setter": false,

package/dist/collection/components/pds-drawer/stories/pds-drawer.stories.js

@@ -9,6 +9,7 @@ export default {
     size: 'md',
     scrollable: true,
     lightDismiss: true,
+    modal: false,
     initialFocus: 'auto',
     open: false,
   },
@@ -28,12 +29,13 @@ const BaseTemplate = (args) => html`
       size="${args.size}"
       scrollable="${args.scrollable}"
       light-dismiss="${args.lightDismiss}"
+      ?modal=${args.modal}
       initial-focus="${args.initialFocus}"
       ?open=${args.open}
     >
       <pds-drawer-header>
         <pds-box align-items="center" justify-content="space-between" fit>
-          <pds-text tag="h2" size="h4">Drawer Title</pds-text>
+          <pds-text tag="h2" size="h4" id="${args.componentId}-heading">Drawer Title</pds-text>
           <pds-button
             class="pds-drawer__close"
             variant="unstyled"
@@ -70,3 +72,6 @@ StartSide.args = { side: 'start' };
 
 export const Small = BaseTemplate.bind({});
 Small.args = { size: 'sm' };
+
+export const Modal = BaseTemplate.bind({});
+Modal.args = { modal: true, componentId: 'drawer-modal-demo' };

package/dist/collection/components/pds-dropdown-menu/pds-dropdown-menu-item/pds-dropdown-menu-item.js

@@ -60,7 +60,7 @@ export class PdsDropdownMenuItem {
         });
     }
     renderElement() {
-        if (this.href !== undefined) {
+        if (this.href != null) {
             return (h("pds-link", { download: this.download, href: this.disabled ? null : this.href, external: this.external, target: this.target, class: {
                     'pds-dropdown-menu-item__content': true,
                     'has-focus': this.hasFocus
@@ -72,7 +72,7 @@ export class PdsDropdownMenuItem {
             }, tabIndex: this.disabled ? -1 : 0, type: "button", part: "button", onKeyDown: this.handleKeyDown, onFocus: this.handleFocus, onBlur: this.handleBlur, disabled: this.disabled, "aria-disabled": this.disabled ? 'true' : null }, h("slot", null)));
     }
     render() {
-        return (h(Host, { key: '33bd645d7c9547e3fd07429cf795302e6a482296', id: this.componentId, class: { 'is-disabled': this.disabled, 'destructive': !this.disabled && this.destructive }, onClick: () => !this.disabled && this.handleClick(), role: "none", tabIndex: -1, "aria-disabled": this.disabled ? 'true' : null }, this.renderElement()));
+        return (h(Host, { key: '2d499a06768bdc4b9a34774d16c1f1e10804b3d5', id: this.componentId, class: { 'is-disabled': this.disabled, 'destructive': !this.disabled && this.destructive }, onClick: () => !this.disabled && this.handleClick(), role: "none", tabIndex: -1, "aria-disabled": this.disabled ? 'true' : null }, this.renderElement()));
     }
     static get is() { return "pds-dropdown-menu-item"; }
     static get encapsulation() { return "shadow"; }

package/dist/collection/components/pds-dropdown-menu/pds-dropdown-menu.js

@@ -253,15 +253,19 @@ export class PdsDropdownMenu {
             this.focusItemByIndex(prevIndex);
         }
     }
+    // Escape is taken in document's capture phase, before a modal around the menu hears it on
+    // document and closes too.
+    handleEscapeKeyDown(event) {
+        if (!this.isOpen || event.key !== 'Escape' || event.defaultPrevented)
+            return;
+        event.preventDefault();
+        this.closeDropdown();
+    }
     // Handle keyboard events for the dropdown
     handleKeyDown(event) {
         if (!this.isOpen)
             return;
         switch (event.key) {
-            case 'Escape':
-                event.preventDefault();
-                this.closeDropdown();
-                break;
             case 'ArrowDown':
                 event.preventDefault();
                 this.focusNextItem();
@@ -353,7 +357,7 @@ export class PdsDropdownMenu {
         }
     }
     render() {
-        return (h(Host, { key: '0dd585168e8fa86378c4812ce54fd09108861d5b', id: this.componentId }, h("slot", { key: 'c7144f8d6aaebe37b585c6c6230102c013230a9e', name: "trigger", onSlotchange: this.handleTriggerSlotChange }), h("pds-box", { key: '82292e051337141bc9fd83b90292b188b0bb3489', "border-radius": "sm", display: "flex", direction: "column", class: "pds-dropdown-menu--panel is-hidden", shadow: "100", part: "menu-panel" }, h("div", { key: 'c0f49dca14df0ba3885865c51562c380155bf8a8', class: { 'pds-dropdown-menu__header': true, 'is-hidden': !this.hasHeader } }, h("slot", { key: 'dc80c97a8dbb79ab4563524b3dea68d144e8570c', name: "header", onSlotchange: this.handleHeaderSlotChange })), h("div", { key: '29cb56bdf28a0438296f33e0fa86c9da7b51902c', class: "pds-dropdown-menu__items", role: "menu", "aria-orientation": "vertical" }, h("slot", { key: '8f91ceeb1eedc4acc79f09032dedc69a2ba1f99a', onSlotchange: this.handleSlotChange })))));
+        return (h(Host, { key: '18dac4d59ea236fe171f4c16f6571cb1547059c6', id: this.componentId }, h("slot", { key: '95201a75a33ccb70dbd51a5cf9d78c76ebf26f65', name: "trigger", onSlotchange: this.handleTriggerSlotChange }), h("pds-box", { key: '7fc588f40f607ad81ad70bf74a525d078d32a80b', "border-radius": "sm", display: "flex", direction: "column", class: "pds-dropdown-menu--panel is-hidden", shadow: "100", part: "menu-panel" }, h("div", { key: '73d13d94edccb68db7b703f930b50f729334efa8', class: { 'pds-dropdown-menu__header': true, 'is-hidden': !this.hasHeader } }, h("slot", { key: '7066f3a6f71c8961326f38f0509f1c0cc17098ae', name: "header", onSlotchange: this.handleHeaderSlotChange })), h("div", { key: '9f07ec488b688c58c6422b575015ccd364075fe8', class: "pds-dropdown-menu__items", role: "menu", "aria-orientation": "vertical" }, h("slot", { key: 'd0aad3f9ac3b58779669411523adbb8878dec61c', onSlotchange: this.handleSlotChange })))));
     }
     static get is() { return "pds-dropdown-menu"; }
     static get encapsulation() { return "shadow"; }
@@ -426,6 +430,12 @@ export class PdsDropdownMenu {
     static get elementRef() { return "host"; }
     static get listeners() {
         return [{
+                "name": "keydown",
+                "method": "handleEscapeKeyDown",
+                "target": "document",
+                "capture": true,
+                "passive": false
+            }, {
                 "name": "keydown",
                 "method": "handleKeyDown",
                 "target": "window",

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

@@ -72,6 +72,20 @@ function oneRadioPerGroup(elements) {
     const stops = new Set(groups.map((radios) => { var _a; return (_a = radios.find((radio) => radio.checked)) !== null && _a !== void 0 ? _a : radios[0]; }));
     return elements.filter((el) => groupedRadio(el) === null || stops.has(el));
 }
+/** The controls Tab reaches in `root`, in order: visible ones, and one radio per group. */
+function tabbableIn(root) {
+    const found = [];
+    collectTabbable(root, found);
+    // checkVisibility() also drops an element inside a hidden ancestor, whose own computed
+    // display isn't none; such an element can't take focus.
+    const visible = found.filter(el => {
+        if (typeof el.checkVisibility === 'function')
+            return el.checkVisibility({ checkVisibilityCSS: true });
+        const style = window.getComputedStyle(el);
+        return style.display !== 'none' && style.visibility !== 'hidden';
+    });
+    return oneRadioPerGroup(visible);
+}
 /** Whether `node` is `ancestor` or inside it, crossing shadow roots, which `Node.contains` doesn't. */
 function containsComposed(ancestor, node) {
     for (let current = node; current; current = current instanceof ShadowRoot ? current.host : current.parentNode) {
@@ -80,6 +94,34 @@ function containsComposed(ancestor, node) {
     }
     return false;
 }
+/**
+ * Every open modal, with the order it opened in, which ranks top-layer modals and the modals
+ * inside them. Kept here rather than queried from the document, which can't see a modal inside
+ * another component's shadow root.
+ */
+const openModals = new Map();
+let openSequence = 0;
+/** Whether an open auto popover's panel sits in `root`, including inside shadow roots under it. */
+function hasOpenPopover(root) {
+    if (root.querySelector('[data-pds-popover-open]'))
+        return true;
+    return Array.from(root.querySelectorAll('*')).some(el => !!el.shadowRoot && hasOpenPopover(el.shadowRoot));
+}
+/**
+ * Whether `a` comes before `b` in the page. `compareDocumentPosition` is arbitrary across a shadow
+ * boundary, so each side climbs to its host until both are in the same tree.
+ */
+function precedesComposed(a, b) {
+    // A document has no host, which ends each climb.
+    for (let x = a; x; x = x.getRootNode().host) {
+        for (let y = b; y; y = y.getRootNode().host) {
+            if (x.getRootNode() === y.getRootNode()) {
+                return !!(x.compareDocumentPosition(y) & Node.DOCUMENT_POSITION_FOLLOWING);
+            }
+        }
+    }
+    return false;
+}
 /** The focused element, followed down through shadow roots to the control that has focus. */
 function deepActiveElement() {
     var _a;
@@ -95,7 +137,8 @@ export class PdsModal {
     constructor() {
         this.focusableElements = [];
         /**
-         * Whether the modal can be dismissed by clicking the backdrop
+         * Whether the modal can be dismissed by clicking the backdrop, pressing Escape, or the browser's
+         * own close request (such as a back gesture)
          * @default true
          */
         this.backdropDismiss = true;
@@ -143,19 +186,33 @@ export class PdsModal {
          * Stores the list of focusable elements in the modal
          */
         this.focusableElementsArray = [];
+        // The browser's own close request (an Escape nothing prevented, a back gesture) would close the
+        // dialog without updating `open`, so close it through hideModal() instead, or not at all.
+        this.handleCancel = (e) => {
+            e.preventDefault();
+            if (!this.open)
+                return;
+            // The request reaches the top-layer dialog even when a disableTopLayer modal inside it is on
+            // top; that one closes first, as it would on Escape.
+            const top = this.innermostOpenModal();
+            const target = (top && containsComposed(this.el, top) ? top : this.el);
+            if (target.backdropDismiss)
+                target.hideModal();
+        };
         this.handleBackdropClick = (e) => {
             if (!this.backdropDismiss || !this.open)
                 return;
-            if (e.target.classList.contains('pds-modal__backdrop')) {
+            // This modal's own backdrop; a nested modal's backdrop handles its own clicks.
+            if (e.target === this.modalRef) {
                 e.stopPropagation();
                 // Only close if this is the innermost modal
-                if (this.isInnermostModal()) {
+                if (this.innermostOpenModal() === this.el) {
                     this.hideModal();
                 }
             }
         };
         this.handleKeyDown = (e) => {
-            var _a, _b, _c;
+            var _a, _b, _c, _d;
             // If the modal is not open, don't handle any keyboard events
             if (!this.open)
                 return;
@@ -178,24 +235,39 @@ export class PdsModal {
                 if (!('__pdsActiveElementAtEscape' in eventSnapshot)) {
                     const activeAtDispatch = document.activeElement;
                     eventSnapshot.__pdsActiveElementAtEscape = activeAtDispatch;
+                    // Followed into shadow roots: for a modal inside one, document.activeElement is only the host.
+                    eventSnapshot.__pdsDeepActiveElementAtEscape = deepActiveElement();
                     const topLayerDialog = (_a = activeAtDispatch === null || activeAtDispatch === void 0 ? void 0 : activeAtDispatch.closest('dialog')) !== null && _a !== void 0 ? _a : null;
                     eventSnapshot.__pdsTopLayerDialogAtEscape = topLayerDialog;
                     eventSnapshot.__pdsTopLayerDialogWasModalAtEscape = !!(topLayerDialog && topLayerDialog.matches(':modal'));
+                    // A control that closed on this Escape (a combobox on its own element, a dropdown menu or
+                    // multiselect in document's capture phase) has prevented it before this bubble listener.
+                    // Read before any modal prevents it below.
+                    eventSnapshot.__pdsEscapeHandledInside = e.defaultPrevented;
+                    // Which modal is innermost is read once too: the inner one closing first would make its
+                    // outer modal the innermost by the time that modal's listener runs.
+                    eventSnapshot.__pdsInnermostModalAtEscape = this.innermostOpenModal();
                 }
+                if (eventSnapshot.__pdsEscapeHandledInside)
+                    return;
                 // Leave Escape to a genuinely stacked-above overlay (disableTopLayer's
                 // reason for existing) — not just to anything outside this modal.
                 const active = eventSnapshot.__pdsActiveElementAtEscape;
                 if (this.disableTopLayer &&
                     active &&
                     active !== document.body &&
-                    !this.el.contains(active) &&
-                    this.isStackedAboveOverlay(active, (_b = eventSnapshot.__pdsTopLayerDialogAtEscape) !== null && _b !== void 0 ? _b : null, (_c = eventSnapshot.__pdsTopLayerDialogWasModalAtEscape) !== null && _c !== void 0 ? _c : false)) {
+                    !containsComposed(this.el, (_b = eventSnapshot.__pdsDeepActiveElementAtEscape) !== null && _b !== void 0 ? _b : active) &&
+                    this.isStackedAboveOverlay(active, (_c = eventSnapshot.__pdsTopLayerDialogAtEscape) !== null && _c !== void 0 ? _c : null, (_d = eventSnapshot.__pdsTopLayerDialogWasModalAtEscape) !== null && _d !== void 0 ? _d : false)) {
                     return;
                 }
+                // An open popover inside takes Escape from its own document listener, which runs after this
+                // one, so leave the key for it. Its preventDefault() keeps the native dialog open.
+                if (this.modalRef && hasOpenPopover(this.modalRef))
+                    return;
                 // Always prevent native dialog close behavior
                 e.preventDefault();
                 // Only close if backdropDismiss is enabled and this is the innermost modal
-                if (this.backdropDismiss && this.isInnermostModal()) {
+                if (this.backdropDismiss && eventSnapshot.__pdsInnermostModalAtEscape === this.el) {
                     this.hideModal();
                 }
                 return;
@@ -255,8 +327,6 @@ export class PdsModal {
     }
     componentDidLoad() {
         this.modalRef = this.el.querySelector('.pds-modal__backdrop');
-        // Add keyboard event listener
-        document.addEventListener('keydown', this.handleKeyDown);
         // @Watch('open') only fires on a later change, not the prop's initial
         // value — a modal mounted with `open` already true (static markup, or a
         // framework passing it on first render) would otherwise never call
@@ -272,9 +342,18 @@ export class PdsModal {
     componentDidRender() {
         unwrapReconnectedContent(this.el.querySelector('.pds-modal'), 'dialog.pds-modal__backdrop', '.pds-modal');
     }
+    // Here rather than in componentDidLoad, which runs once: a modal taken out of the page and put
+    // back (a morph or a framework moving it) gets its keyboard handling, and its place among the
+    // open modals, back too. Adding the same listener twice is a no-op.
+    connectedCallback() {
+        document.addEventListener('keydown', this.handleKeyDown);
+        if (this.open && !openModals.has(this.el))
+            openModals.set(this.el, ++openSequence);
+    }
     disconnectedCallback() {
         // Clean up event listener
         document.removeEventListener('keydown', this.handleKeyDown);
+        openModals.delete(this.el);
     }
     handleOpenChange(newValue) {
         if (newValue) {
@@ -290,17 +369,7 @@ export class PdsModal {
     updateFocusableElements() {
         if (!this.modalRef)
             return;
-        this.focusableElements = [];
-        collectTabbable(this.modalRef, this.focusableElements);
-        // checkVisibility() also drops an element inside a hidden ancestor, whose own computed
-        // display isn't none; such an element can't take focus, so it can't anchor the trap.
-        this.focusableElements = this.focusableElements.filter(el => {
-            if (typeof el.checkVisibility === 'function')
-                return el.checkVisibility({ checkVisibilityCSS: true });
-            const style = window.getComputedStyle(el);
-            return style.display !== 'none' && style.visibility !== 'hidden';
-        });
-        this.focusableElements = oneRadioPerGroup(this.focusableElements);
+        this.focusableElements = tabbableIn(this.modalRef);
     }
     /**
      * Sets focus to the first focusable element in the modal
@@ -324,10 +393,13 @@ export class PdsModal {
      * Opens the modal
      */
     async showModal() {
+        var _a;
         if (this.modalRef) {
             try {
-                // Store the currently focused element to restore focus when modal closes
-                this.previousActiveElement = document.activeElement;
+                // Store the currently focused element to restore focus when modal closes. Showing an open
+                // modal again (the open watcher does) would record a control inside it instead.
+                if (!this.modalRef.open)
+                    this.previousActiveElement = document.activeElement;
                 // showModal() promotes the dialog to the browser top layer (and makes the
                 // rest of the page inert), which prevents any overlay outside the dialog
                 // from ever painting above it. show() opens a non-modal dialog that stays
@@ -339,11 +411,25 @@ export class PdsModal {
                     this.modalRef.showModal();
                 }
                 this.open = true;
+                // Showing an open modal again doesn't move it above one opened after it.
+                if (!openModals.has(this.el))
+                    openModals.set(this.el, ++openSequence);
                 // Update focusable elements and set initial focus
                 // Using a longer timeout to ensure all components are fully rendered
+                const openedAs = (_a = openModals.get(this.el)) !== null && _a !== void 0 ? _a : 0;
                 setTimeout(() => {
                     var _a, _b;
                     this.updateFocusableElements();
+                    // A modal opened above this one in the meantime has focus; don't take it back. Not this
+                    // modal itself (moving it gives it a new place), and not a disableTopLayer modal outside
+                    // it while this one is in the top layer, which sits below it.
+                    const openedAbove = Array.from(openModals).some(([modal, sequence]) => sequence > openedAs &&
+                        modal !== this.el &&
+                        (containsComposed(this.el, modal) || !modal.disableTopLayer || this.disableTopLayer));
+                    if (openedAbove) {
+                        this.pdsModalOpen.emit();
+                        return;
+                    }
                     if (this.disableInitialFocus) {
                         // show()/showModal() also move focus into the dialog natively (the
                         // HTML spec's "dialog focusing steps") — that native step isn't
@@ -387,6 +473,7 @@ export class PdsModal {
      * Closes the modal
      */
     async hideModal() {
+        var _a;
         if (this.modalRef) {
             try {
                 // Capture before close(): with the async task queue, a prop change
@@ -401,11 +488,19 @@ export class PdsModal {
                 const focusAlreadyMovedElsewhere = activeElement !== null && activeElement !== document.body && !this.modalRef.contains(activeElement);
                 this.modalRef.close();
                 this.open = false;
-                // Restore focus to the element that was focused before the modal was opened
-                if (!focusAlreadyMovedElsewhere &&
-                    this.previousActiveElement &&
-                    typeof this.previousActiveElement.focus === 'function') {
-                    this.previousActiveElement.focus();
+                openModals.delete(this.el);
+                // Restore focus to the element that was focused before the modal was opened. If that's
+                // gone or can't take focus (disabled, hidden, or nothing), fall back to the open modal now
+                // on top, so focus doesn't land on an inert page behind it.
+                if (!focusAlreadyMovedElsewhere) {
+                    const previous = this.previousActiveElement;
+                    if (previous && previous !== document.body && previous.isConnected)
+                        (_a = previous.focus) === null || _a === void 0 ? void 0 : _a.call(previous);
+                    const active = deepActiveElement();
+                    // document.body isn't a real restore target — it's just where focus lands when nothing
+                    // was focused before opening, so landing back there never counts as a successful restore.
+                    if (!previous || previous === document.body || !containsComposed(previous, active) || containsComposed(this.el, active))
+                        this.focusTopModal();
                 }
                 this.pdsModalClose.emit();
             }
@@ -414,12 +509,29 @@ export class PdsModal {
             }
         }
     }
+    /**
+     * Focuses the first control of the open modal now on top, when the page behind it is inert: that
+     * modal is in the top layer (or paints there inside a top-layer one), or it wraps this one. A
+     * non-modal one over an interactive page, like a drawer, is left alone.
+     */
+    focusTopModal() {
+        var _a;
+        const top = this.innermostOpenModal();
+        const dialog = top === null || top === void 0 ? void 0 : top.querySelector('.pds-modal__backdrop');
+        if (!dialog)
+            return;
+        if (!closest('dialog:modal', dialog) && !containsComposed(top, this.el))
+            return;
+        (_a = tabbableIn(dialog).find(el => !containsComposed(this.el, el))) === null || _a === void 0 ? void 0 : _a.focus();
+    }
     /**
      * Gets the z-index of a modal's backdrop element
      */
     getBackdropZIndex(modal) {
         const backdrop = modal.querySelector('.pds-modal__backdrop');
-        return backdrop ? parseInt(getComputedStyle(backdrop).zIndex, 10) : -1;
+        // `auto` (no z-index token loaded) parses to NaN, which no comparison can rank.
+        const zIndex = backdrop ? parseInt(getComputedStyle(backdrop).zIndex, 10) : -1;
+        return Number.isNaN(zIndex) ? 0 : zIndex;
     }
     /**
      * Whether `active` sits inside a surface actually stacked above this modal.
@@ -446,7 +558,8 @@ export class PdsModal {
      * lose that evidence depending on listener order.
      */
     isStackedAboveOverlay(active, topLayerDialog, topLayerDialogWasModal) {
-        if (topLayerDialog && topLayerDialog !== this.modalRef && topLayerDialogWasModal) {
+        // A top-layer dialog this modal sits inside is underneath it, not an overlay above.
+        if (topLayerDialog && topLayerDialog !== this.modalRef && topLayerDialogWasModal && !containsComposed(topLayerDialog, this.el)) {
             return true;
         }
         const ownZIndex = this.getBackdropZIndex(this.el);
@@ -462,24 +575,37 @@ export class PdsModal {
         return false;
     }
     /**
-     * Checks if this modal is the innermost (highest z-index) modal
+     * The open modal that takes Escape or a backdrop click, among those with no other open modal
+     * inside them (a nested modal's backdrop can share its outer modal's z-index). A top-layer dialog
+     * (or a modal inside one) paints above anything outside it, and within the top layer the last
+     * opened is on top. Modals in the same layer (the page, or one top-layer dialog) then rank by
+     * the highest backdrop, then the one later in the page.
      */
-    isInnermostModal() {
-        // Find all open modals
-        const openModals = Array.from(document.querySelectorAll('pds-modal')).filter(modal => modal.open);
-        if (openModals.length === 0)
-            return false;
-        // Get this modal's backdrop element
-        const thisBackdrop = this.el.querySelector('.pds-modal__backdrop');
-        if (!thisBackdrop)
-            return false;
-        // Get computed z-index of all open modal backdrops
-        const modalZIndexes = openModals.map(modal => this.getBackdropZIndex(modal));
-        // Get the highest z-index
-        const maxZIndex = Math.max(...modalZIndexes);
-        // Check if this modal's backdrop has the highest z-index
-        const thisZIndex = this.getBackdropZIndex(this.el);
-        return thisZIndex === maxZIndex;
+    innermostOpenModal() {
+        const open = Array.from(openModals.keys()).filter(modal => modal.isConnected);
+        const innermost = open.filter(modal => !open.some(other => other !== modal && containsComposed(modal, other)));
+        const byDocumentOrder = [...innermost].sort((a, b) => (precedesComposed(a, b) ? -1 : 1));
+        // A modal inside a top-layer dialog paints in that dialog's place in the top layer, even when it
+        // isn't in the top layer itself (disableTopLayer), so that dialog's open order ranks it first.
+        const rank = (modal) => {
+            var _a;
+            const backdrop = modal.querySelector('.pds-modal__backdrop');
+            const topLayerDialog = backdrop ? closest('dialog:modal', backdrop) : null;
+            const topLayerModal = topLayerDialog === null || topLayerDialog === void 0 ? void 0 : topLayerDialog.closest('pds-modal');
+            const layer = topLayerDialog ? ((_a = (topLayerModal && openModals.get(topLayerModal))) !== null && _a !== void 0 ? _a : 0) : 0;
+            return [topLayerDialog ? 1 : 0, layer, this.getBackdropZIndex(modal), byDocumentOrder.indexOf(modal)];
+        };
+        let top = null;
+        let topRank = [-1, -1, -1, -1];
+        for (const modal of innermost) {
+            const modalRank = rank(modal);
+            const above = modalRank.findIndex((value, i) => value !== topRank[i]);
+            if (above >= 0 && modalRank[above] > topRank[above]) {
+                top = modal;
+                topRank = modalRank;
+            }
+        }
+        return top;
     }
     /** Whether a modal dialog other than this one sits between the focused element and this modal. */
     modalDialogAbove(active) {
@@ -519,14 +645,14 @@ export class PdsModal {
     }
     render() {
         const [sizeClass = 'md', customSize] = this.resolveSize();
-        return (h("dialog", { key: '12ea38928ea287f16ffa33e246caa2bfde6fc130', class: {
+        return (h("dialog", { key: '0b187f36910a859afe57b891f1ebffd1d2d49ab7', class: {
                 'pds-modal__backdrop': true,
                 'open': this.open
-            }, "aria-modal": this.disableTopLayer ? 'false' : 'true', "aria-labelledby": `${this.componentId}-heading`, onClick: this.handleBackdropClick }, h("div", { key: 'b9d83cabda56c315d9115f7030e3bdbcf923ec08', class: {
+            }, "aria-modal": this.disableTopLayer ? 'false' : 'true', "aria-labelledby": `${this.componentId}-heading`, onClick: this.handleBackdropClick, onCancel: this.handleCancel }, h("div", { key: 'f5e652d4dae0e7c272b37b63eb9c65f04c69536a', class: {
                 'pds-modal': true,
                 [`pds-modal--${sizeClass}`]: true,
                 'pds-modal--scrollable': this.scrollable
-            }, style: customSize !== undefined ? { '--pds-modal-max-width': customSize } : undefined, part: "modal" }, h("slot", { key: '3c5edad1482cb124e503197adf411890573b076d' }))));
+            }, style: customSize !== undefined ? { '--pds-modal-max-width': customSize } : undefined, part: "modal" }, h("slot", { key: 'a954e1694741f78230599c476b270079797a263e' }))));
     }
     static get is() { return "pds-modal"; }
     static get originalStyleUrls() {
@@ -556,7 +682,7 @@ export class PdsModal {
                             "name": "default",
                             "text": "true"
                         }],
-                    "text": "Whether the modal can be dismissed by clicking the backdrop"
+                    "text": "Whether the modal can be dismissed by clicking the backdrop, pressing Escape, or the browser's\nown close request (such as a back gesture)"
                 },
                 "getter": false,
                 "setter": false,
@@ -763,6 +889,10 @@ export class PdsModal {
                         "HTMLElement": {
                             "location": "global",
                             "id": "global::HTMLElement"
+                        },
+                        "HTMLPdsModalElement": {
+                            "location": "global",
+                            "id": "global::HTMLPdsModalElement"
                         }
                     },
                     "return": "Promise<void>"