@unofficialbox/box-open-elements 0.8.0 → 0.10.0

package/dist/components/overlays/command-palette.d.ts

@@ -16,6 +16,7 @@ export declare class CommandPalette extends BaseElement {
     static readonly tagName: string;
     static get observedAttributes(): string[];
     private hostEl;
+    private backdropEl;
     private readonly focusRestore;
     private openValue;
     private wasOpen;

package/dist/components/overlays/command-palette.js

@@ -1,5 +1,6 @@
 import { groupCommandMatches, isCommandDescriptorRecord, matchCommands, splitCommandLabel, } from "./command-types.js";
 import { BaseElement } from "../../core/index.js";
+import { dismissModal, promoteModal } from "../../foundations/overlay/index.js";
 import { FocusRestore, trapTabKey } from "../../foundations/a11y/index.js";
 import { boeOverlay, boePanel, boeRadius } from "../../foundations/geometry/index.js";
 import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
@@ -19,6 +20,10 @@ const elementStyles = `
           display: contents;
         }
 
+        /* A <dialog> promoted with showModal() — see
+           foundations/overlay/top-layer.ts. The top layer keeps the scrim above
+           the page without moving the host node. UA border/margin/max-* reset
+           because this is the full-viewport scrim, not a centred card. */
         [part="backdrop"] {
           position: fixed;
           inset: 0;
@@ -28,6 +33,24 @@ const elementStyles = `
           padding-block-start: 12vh;
           background: ${boeOverlay.modalBackdrop};
           z-index: 1000;
+          border: 0;
+          margin: 0;
+          max-width: none;
+          max-height: none;
+          width: auto;
+          height: auto;
+          color: inherit;
+        }
+
+        /* The scrim paints itself; the UA pseudo must not double it up. */
+        [part="backdrop"]::backdrop {
+          background: transparent;
+        }
+
+        /* Without showModal support the element stays hidden, which is the
+           correct closed state anyway. */
+        [part="backdrop"]:not([open]) {
+          display: none;
         }
 
         [part="palette"] {
@@ -185,6 +208,7 @@ export class CommandPalette extends BaseElement {
         return ["commands", "hide-disabled", "hotkey", "open", "placeholder"];
     }
     hostEl;
+    backdropEl = null;
     focusRestore = new FocusRestore();
     openValue = false;
     wasOpen = false;
@@ -449,6 +473,9 @@ export class CommandPalette extends BaseElement {
         this.openValue = this.open;
         if (!this.openValue) {
             const wasOpen = this.wasOpen;
+            // Leave the top layer before the element is discarded, not after.
+            dismissModal(this.backdropEl);
+            this.backdropEl = null;
             this.hostEl.innerHTML = "";
             this.rankedMatches = [];
             this.wasOpen = false;
@@ -486,8 +513,8 @@ export class CommandPalette extends BaseElement {
         const activeId = this.rankedMatches.length > 0 ? `command-option-${String(this.activeIndex)}` : "";
         if (justOpened || !this.hostEl.querySelector('[part="palette"]')) {
             this.hostEl.innerHTML = `
-        <div part="backdrop">
-          <div part="palette" role="dialog" aria-modal="true" aria-label="Command palette">
+        <dialog part="backdrop" aria-label="Command palette">
+          <div part="palette">
             <div part="search-row">
               <span part="search-icon" aria-hidden="true">⌕</span>
               <input
@@ -511,9 +538,21 @@ export class CommandPalette extends BaseElement {
               <span><span part="footer-key">esc</span> close</span>
             </div>
           </div>
-        </div>
+        </dialog>
       `;
         }
+        const freshScrim = this.backdropEl === null;
+        this.backdropEl = this.hostEl.querySelector('[part="backdrop"]');
+        if (freshScrim && this.backdropEl) {
+            // A modal dialog closes itself on Escape and fires `cancel`; route it
+            // through the component's own dismissal so `open` stays in sync.
+            this.backdropEl.addEventListener("cancel", event => {
+                event.preventDefault();
+                this.dispatchEvent(new CustomEvent("dismissed", { bubbles: true, composed: true }));
+                this.open = false;
+            });
+        }
+        promoteModal(this.backdropEl);
         const input = this.hostEl.querySelector('[part="search"]');
         const results = this.hostEl.querySelector('[part="results"]');
         const empty = this.hostEl.querySelector('[part="empty"]');

package/dist/components/overlays/context-menu.js

@@ -1,4 +1,5 @@
 import { BaseElement } from "../../core/index.js";
+import { dismissPopover, promotePopover } from "../../foundations/overlay/index.js";
 import { FocusRestore, nextRovingIndex } from "../../foundations/a11y/index.js";
 import { boeOverlay, boeRadius, boeSpace } from "../../foundations/geometry/index.js";
 import { resolvePosition } from "../../foundations/overlay/index.js";
@@ -19,7 +20,12 @@ const contextMenuStyles = `
     display: contents;
   }
 
+  /* display is stated explicitly because the element carries
+     popover="manual": the UA sheet hides a popover that is not open, and an
+     author declaration outranks it. If showPopover() is unavailable or fails,
+     this still renders as before and only the top layer is lost. */
   [part="surface"] {
+    display: grid;
     position: fixed;
     z-index: 40;
     inset-block-start: 0;
@@ -136,7 +142,7 @@ export class ContextMenu extends BaseElement {
         this.shadowRoot.innerHTML = `
       <style>${contextMenuStyles}</style>
       <div part="target"><slot></slot></div>
-      <div part="surface" role="menu" hidden></div>
+      <div part="surface" popover="manual" role="menu" hidden></div>
     `;
         this.targetEl = this.shadowRoot.querySelector('[part="target"]');
         this.surfaceEl = this.shadowRoot.querySelector('[part="surface"]');
@@ -194,6 +200,9 @@ export class ContextMenu extends BaseElement {
     openAt(clientX, clientY) {
         this.renderItems();
         this.surfaceEl.hidden = false;
+        // Top layer keeps the menu above the page even inside an ancestor with a
+        // transform/filter/contain, which position:fixed alone cannot escape.
+        promotePopover(this.surfaceEl);
         const { width, height } = this.surfaceEl.getBoundingClientRect();
         const { x, y } = resolvePosition({ top: clientY, left: clientX, width: 0, height: 0 }, { width, height }, { width: window.innerWidth, height: window.innerHeight }, { placement: { side: "bottom", align: "start" }, offset: 0 });
         this.surfaceEl.style.left = `${Math.round(x)}px`;
@@ -209,6 +218,7 @@ export class ContextMenu extends BaseElement {
             return;
         this.openValue = false;
         this.surfaceEl.hidden = true;
+        dismissPopover(this.surfaceEl);
         this.unbindDocument();
         this.dispatchEvent(new CustomEvent("open-changed", { bubbles: true, composed: true, detail: { open: false } }));
         this.focusRestore.restore();

package/dist/components/overlays/dialog.d.ts

@@ -9,6 +9,7 @@ export declare class Dialog extends BaseElement {
     private hostEl;
     private titleEl;
     private descriptionEl;
+    private backdropEl;
     private confirmEl;
     private readonly focusRestore;
     get open(): boolean;

package/dist/components/overlays/dialog.js

@@ -1,4 +1,5 @@
 import { BaseElement } from "../../core/index.js";
+import { dismissModal, promoteModal } from "../../foundations/overlay/index.js";
 import { FocusRestore, trapTabKey } from "../../foundations/a11y/index.js";
 import { boeControl, boeOverlay, boeRadius, boeSpace } from "../../foundations/geometry/index.js";
 import { boeBrandInteractiveStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/index.js";
@@ -9,6 +10,12 @@ const dialogStyles = `
     font: inherit;
   }
 
+  /* A <dialog> promoted with showModal(), not a plain box — see
+     foundations/overlay/top-layer.ts. The top layer keeps the scrim above the
+     page without moving the host node, so an ancestor with a transform,
+     filter, or contain cannot clip it. The UA sheet's border/padding/margin and
+     max-* are reset because this element is the full-viewport scrim rather
+     than a centred card. */
   [part="backdrop"] {
     position: fixed;
     inset: 0;
@@ -17,6 +24,24 @@ const dialogStyles = `
     display: grid;
     place-items: center;
     padding: ${boeOverlay.modalPadding};
+    border: 0;
+    margin: 0;
+    max-width: none;
+    max-height: none;
+    width: auto;
+    height: auto;
+    color: inherit;
+  }
+
+  /* The scrim paints itself; the UA pseudo must not double it up. */
+  [part="backdrop"]::backdrop {
+    background: transparent;
+  }
+
+  /* Without showModal support the element stays hidden, which is the correct
+     closed state anyway. */
+  [part="backdrop"]:not([open]) {
+    display: none;
   }
 
   [part="dialog"] {
@@ -116,6 +141,7 @@ export class Dialog extends BaseElement {
     hostEl;
     titleEl = null;
     descriptionEl = null;
+    backdropEl = null;
     confirmEl = null;
     focusRestore = new FocusRestore();
     get open() {
@@ -242,6 +268,9 @@ export class Dialog extends BaseElement {
         if (!this.openValue) {
             const wasOpen = this.wasOpen;
             this.setScrollLock(false);
+            // Leave the top layer before the element is discarded, not after.
+            dismissModal(this.backdropEl);
+            this.backdropEl = null;
             this.hostEl.innerHTML = "";
             this.titleEl = null;
             this.descriptionEl = null;
@@ -261,8 +290,8 @@ export class Dialog extends BaseElement {
         if (!this.hostEl.querySelector('[part="dialog"]')) {
             this.hostEl.innerHTML = `
         <style>${dialogStyles}</style>
-        <div part="backdrop">
-          <section part="dialog" role="dialog" aria-modal="true" tabindex="-1" aria-labelledby="dialog-title" data-size="${this.size}">
+        <dialog part="backdrop" aria-labelledby="dialog-title">
+          <section part="dialog" tabindex="-1" data-size="${this.size}">
             <header part="header">
               <h2 id="dialog-title"></h2>
             </header>
@@ -273,9 +302,20 @@ export class Dialog extends BaseElement {
               <button type="button" part="confirm"></button>
             </footer>
           </section>
-        </div>
+        </dialog>
       `;
         }
+        const freshScrim = this.backdropEl === null;
+        this.backdropEl = this.hostEl.querySelector('[part="backdrop"]');
+        if (freshScrim && this.backdropEl) {
+            // A modal dialog closes itself on Escape and fires `cancel`. Left alone
+            // that would bypass close(), leaving `open` true with the dialog gone.
+            this.backdropEl.addEventListener("cancel", event => {
+                event.preventDefault();
+                this.close();
+            });
+        }
+        promoteModal(this.backdropEl);
         this.titleEl = this.hostEl.querySelector("#dialog-title");
         this.descriptionEl = this.hostEl.querySelector('[part="description"]');
         this.confirmEl = this.hostEl.querySelector('[part="confirm"]');

package/dist/components/overlays/drawer.d.ts

@@ -9,8 +9,6 @@ export declare class Drawer extends BaseElement {
     private openValue;
     private wasOpen;
     private readonly focusRestore;
-    private placeholder;
-    private portaled;
     private hostEl;
     private backdropEl;
     private drawerEl;
@@ -30,12 +28,25 @@ export declare class Drawer extends BaseElement {
     set busy(value: boolean);
     get heading(): string;
     set heading(value: string);
-    connectedCallback(): void;
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     show(): void;
     close(): void;
-    private portalToBody;
-    private restoreFromPortal;
+    disconnectedCallback(): void;
+    /**
+     * Promote the scrim into the top layer.
+     *
+     * `showModal` is the whole point of the `<dialog>`: it renders outside the
+     * normal flow, so the drawer covers the viewport without the host node being
+     * moved anywhere. The previous implementation relocated the host to
+     * `document.body`, which worked visually and broke every framework that owns
+     * the node — React unmounting a tree containing an open drawer threw
+     * `NotFoundError`, because the node it tried to remove was no longer its
+     * child.
+     *
+     * The guards live in the shared foundation, which every overlay now uses.
+     */
+    private promoteTopLayer;
+    private dismissTopLayer;
     protected renderTemplate(): void;
     /**
      * The unsaved-changes guard, host-owned: `dismiss` is cancelable, and a

package/dist/components/overlays/drawer.js

@@ -1,5 +1,6 @@
 import { BaseElement } from "../../core/index.js";
 import { FocusRestore, trapTabKey } from "../../foundations/a11y/index.js";
+import { dismissModal, promoteModal } from "../../foundations/overlay/index.js";
 import { boeControl, boeOverlay, boePanel, boeRadius, boeSpace, } from "../../foundations/geometry/index.js";
 import { boeNeutralInteractiveStyles } from "../../foundations/tokens/index.js";
 const DEFAULT_TAG_NAME = "box-drawer";
@@ -9,12 +10,39 @@ const drawerStyles = `
     font: inherit;
   }
 
+  /* A <dialog> promoted with showModal(), not a plain box. The top layer is
+     what lets the drawer cover the page without the host node being moved
+     there: it renders outside the normal flow, so an ancestor with a
+     transform, filter, or contain — which would otherwise make position:fixed
+     resolve against that ancestor instead of the viewport — cannot clip it.
+     The UA sheet's border, padding, margin, and max-* are reset because this
+     element is the full-viewport scrim, not a centred card. */
   [part="backdrop"] {
     position: fixed;
     inset: 0;
     display: grid;
     z-index: 1200;
     background: ${boeOverlay.modalBackdrop};
+    border: 0;
+    padding: 0;
+    margin: 0;
+    max-width: none;
+    max-height: none;
+    width: auto;
+    height: auto;
+    color: inherit;
+  }
+
+  /* The scrim is painted by the element itself, so the UA backdrop pseudo
+     must not double it up. */
+  [part="backdrop"]::backdrop {
+    background: transparent;
+  }
+
+  /* Only an open dialog participates in layout; without showModal support the
+     element stays display:none, which is the correct closed state anyway. */
+  [part="backdrop"]:not([open]) {
+    display: none;
   }
 
   [part="drawer"] {
@@ -178,8 +206,6 @@ export class Drawer extends BaseElement {
     openValue = false;
     wasOpen = false;
     focusRestore = new FocusRestore();
-    placeholder = null;
-    portaled = false;
     hostEl;
     backdropEl = null;
     drawerEl = null;
@@ -235,21 +261,9 @@ export class Drawer extends BaseElement {
     set heading(value) {
         this.setAttribute("heading", value);
     }
-    connectedCallback() {
-        if (this.openValue) {
-            this.portalToBody();
-        }
-        super.connectedCallback();
-    }
     attributeChangedCallback(name, oldValue, newValue) {
         if (name === "open") {
             this.openValue = this.hasAttribute("open");
-            if (this.openValue) {
-                this.portalToBody();
-            }
-            else {
-                this.restoreFromPortal();
-            }
         }
         super.attributeChangedCallback(name, oldValue, newValue);
     }
@@ -258,29 +272,31 @@ export class Drawer extends BaseElement {
     }
     close() {
         this.open = false;
-        this.restoreFromPortal();
     }
-    portalToBody() {
-        if (this.portaled || !this.isConnected || !this.ownerDocument?.body) {
-            return;
-        }
-        const parent = this.parentNode;
-        if (!parent || parent === this.ownerDocument.body) {
-            return;
-        }
-        this.placeholder = this.ownerDocument.createComment("box-drawer-placeholder");
-        parent.insertBefore(this.placeholder, this);
-        this.ownerDocument.body.append(this);
-        this.portaled = true;
+    disconnectedCallback() {
+        // A dialog removed from the document while modal leaves the top layer
+        // behind it in some engines; closing first keeps that bookkeeping honest.
+        this.dismissTopLayer();
+        super.disconnectedCallback();
     }
-    restoreFromPortal() {
-        if (!this.portaled || !this.placeholder?.parentNode) {
-            return;
-        }
-        this.placeholder.parentNode.insertBefore(this, this.placeholder);
-        this.placeholder.remove();
-        this.placeholder = null;
-        this.portaled = false;
+    /**
+     * Promote the scrim into the top layer.
+     *
+     * `showModal` is the whole point of the `<dialog>`: it renders outside the
+     * normal flow, so the drawer covers the viewport without the host node being
+     * moved anywhere. The previous implementation relocated the host to
+     * `document.body`, which worked visually and broke every framework that owns
+     * the node — React unmounting a tree containing an open drawer threw
+     * `NotFoundError`, because the node it tried to remove was no longer its
+     * child.
+     *
+     * The guards live in the shared foundation, which every overlay now uses.
+     */
+    promoteTopLayer() {
+        promoteModal(this.backdropEl);
+    }
+    dismissTopLayer() {
+        dismissModal(this.backdropEl);
     }
     renderTemplate() {
         if (!this.shadowRoot) {
@@ -343,6 +359,8 @@ export class Drawer extends BaseElement {
         }
         if (!this.openValue) {
             const wasOpen = this.wasOpen;
+            // Leave the top layer before the element is discarded, not after.
+            this.dismissTopLayer();
             this.hostEl.innerHTML = "";
             this.backdropEl = null;
             this.drawerEl = null;
@@ -362,8 +380,8 @@ export class Drawer extends BaseElement {
         if (!this.hostEl.querySelector('[part="drawer"]')) {
             this.hostEl.innerHTML = `
         <style>${drawerStyles}</style>
-        <div part="backdrop">
-          <aside part="drawer" role="dialog" aria-modal="true" aria-labelledby="drawer-title">
+        <dialog part="backdrop" aria-labelledby="drawer-title">
+          <aside part="drawer">
             <header part="header">
               <div part="meta">
                 <h2 id="drawer-title"></h2>
@@ -380,7 +398,7 @@ export class Drawer extends BaseElement {
               <slot name="footer"></slot>
             </footer>
           </aside>
-        </div>
+        </dialog>
       `;
             // The footer row only exists when the host slots one: an empty sticky
             // bar would just eat drawer height.
@@ -388,8 +406,18 @@ export class Drawer extends BaseElement {
             footerSlot?.addEventListener("slotchange", () => {
                 this.syncFooter();
             });
+            // A modal dialog closes itself on Escape and fires `cancel`. Left alone
+            // that would bypass the cancelable `dismiss` contract entirely — a host
+            // calling preventDefault() would keep `open` true while the dialog had
+            // already gone. Route it through the same guard as every other dismissal.
+            const dialogEl = this.hostEl.querySelector('[part="backdrop"]');
+            dialogEl?.addEventListener("cancel", event => {
+                event.preventDefault();
+                this.requestDismiss("escape");
+            });
         }
         this.backdropEl = this.hostEl.querySelector('[part="backdrop"]');
+        this.promoteTopLayer();
         this.drawerEl = this.hostEl.querySelector('[part="drawer"]');
         this.titleEl = this.hostEl.querySelector("#drawer-title");
         this.descriptionEl = this.hostEl.querySelector('[part="description"]');

package/dist/components/overlays/guide-tooltip.js

@@ -1,4 +1,5 @@
 import { BaseElement } from "../../core/index.js";
+import { dismissPopover, promotePopover } from "../../foundations/overlay/index.js";
 import { boeControl, boeOverlay, boeRadius, boeSpace } from "../../foundations/geometry/index.js";
 import { boeNeutralInteractiveStyles } from "../../foundations/tokens/index.js";
 import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
@@ -13,7 +14,12 @@ const guideTooltipStyles = `
 
   /* Positioned by JS (foundations/overlay) as a viewport-fixed callout, so it
      escapes ancestor overflow and flips/shifts to stay on-screen. */
+  /* display is stated explicitly because the element carries
+     popover="manual": the UA sheet hides a popover that is not open, and an
+     author declaration outranks it. If showPopover() is unavailable or fails,
+     this still renders as before and only the top layer is lost. */
   [part="callout"] {
+    display: block;
     position: fixed;
     inset-block-start: 0;
     inset-inline-start: 0;
@@ -283,7 +289,7 @@ export class GuideTooltip extends BaseElement {
         this.shadowRoot.innerHTML = `
       <style>${guideTooltipStyles}</style>
       <slot name="anchor"></slot>
-      <div part="callout" role="dialog" aria-labelledby="${this.headingId}" hidden>
+      <div part="callout" popover="manual" role="dialog" aria-labelledby="${this.headingId}" hidden>
         <button type="button" part="close" aria-label="Close">
           <svg viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path d="M4 4l8 8M12 4l-8 8" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg>
         </button>
@@ -329,6 +335,14 @@ export class GuideTooltip extends BaseElement {
             return;
         }
         this.calloutEl.hidden = !this.openValue;
+        // Top layer keeps it above the page even inside an ancestor with a
+        // transform/filter/contain, which position:fixed alone cannot escape.
+        if (this.openValue) {
+            promotePopover(this.calloutEl);
+        }
+        else {
+            dismissPopover(this.calloutEl);
+        }
         const heading = this.heading;
         this.headingEl.hidden = !heading;
         this.headingEl.textContent = heading;

package/dist/components/overlays/popover.js

@@ -1,4 +1,5 @@
 import { BaseElement } from "../../core/index.js";
+import { dismissPopover, promotePopover } from "../../foundations/overlay/index.js";
 import { FocusRestore, getTabbableElements } from "../../foundations/a11y/index.js";
 import { boeControl, boeOverlay, boeRadius } from "../../foundations/geometry/index.js";
 import { boeNeutralInteractiveStyles } from "../../foundations/tokens/index.js";
@@ -51,7 +52,13 @@ const popoverStyles = `
   /* Positioned by JS (foundations/overlay) as position: fixed in viewport
      coordinates — so it escapes ancestor overflow and flips/shifts to stay in
      view, the job a portal does in box-ui-elements. */
+  /* display is stated explicitly, not left to the initial value, because the
+     element carries popover="manual": the UA sheet hides a popover that is not
+     open, and an author declaration outranks it. So if showPopover() is
+     unavailable or fails, the surface still renders exactly as before and only
+     the top-layer promotion is lost — see foundations/overlay/top-layer.ts. */
   [part="surface"] {
+    display: block;
     position: fixed;
     z-index: 30;
     inset-block-start: 0;
@@ -246,7 +253,7 @@ export class Popover extends BaseElement {
       <style>${popoverStyles}</style>
       <div part="container">
         <button type="button" part="trigger" id="boe-popover-trigger" aria-haspopup="dialog" aria-controls="boe-popover-surface"></button>
-        <div part="surface" role="dialog" id="boe-popover-surface" aria-labelledby="boe-popover-trigger" tabindex="-1" hidden>
+        <div part="surface" popover="manual" role="dialog" id="boe-popover-surface" aria-labelledby="boe-popover-trigger" tabindex="-1" hidden>
           <slot></slot>
         </div>
       </div>
@@ -288,6 +295,14 @@ export class Popover extends BaseElement {
         const justOpened = this.openValue && !this.wasOpen;
         const justClosed = !this.openValue && this.wasOpen;
         this.surfaceEl.hidden = !this.openValue;
+        // Top layer keeps the surface above the page even inside an ancestor with
+        // a transform/filter/contain, which position:fixed alone cannot escape.
+        if (this.openValue) {
+            promotePopover(this.surfaceEl);
+        }
+        else {
+            dismissPopover(this.surfaceEl);
+        }
         this.syncDocumentListeners();
         if (this.openValue) {
             this.startPositioning();

package/dist/components/overlays/shortcuts-overlay.d.ts

@@ -16,6 +16,7 @@ export declare class ShortcutsOverlay extends BaseElement {
     static readonly tagName: string;
     static get observedAttributes(): string[];
     private hostEl;
+    private backdropEl;
     private readonly focusRestore;
     private wasOpen;
     private commandsRaw;

package/dist/components/overlays/shortcuts-overlay.js

@@ -1,5 +1,6 @@
 import { groupShortcutCommands, isCommandDescriptorRecord, splitShortcutKeys, } from "./command-types.js";
 import { BaseElement } from "../../core/index.js";
+import { dismissModal, promoteModal } from "../../foundations/overlay/index.js";
 import { FocusRestore, trapTabKey } from "../../foundations/a11y/index.js";
 import { boeOverlay, boePanel, boeRadius } from "../../foundations/geometry/index.js";
 const DEFAULT_TAG_NAME = "box-shortcuts-overlay";
@@ -37,6 +38,10 @@ const elementStyles = `
           display: contents;
         }
 
+        /* A <dialog> promoted with showModal() — see
+           foundations/overlay/top-layer.ts. The top layer keeps the scrim above
+           the page without moving the host node. UA border/margin/max-* reset
+           because this is the full-viewport scrim, not a centred card. */
         [part="backdrop"] {
           position: fixed;
           inset: 0;
@@ -46,6 +51,24 @@ const elementStyles = `
           padding: 1rem;
           background: ${boeOverlay.modalBackdrop};
           z-index: 1000;
+          border: 0;
+          margin: 0;
+          max-width: none;
+          max-height: none;
+          width: auto;
+          height: auto;
+          color: inherit;
+        }
+
+        /* The scrim paints itself; the UA pseudo must not double it up. */
+        [part="backdrop"]::backdrop {
+          background: transparent;
+        }
+
+        /* Without showModal support the element stays hidden, which is the
+           correct closed state anyway. */
+        [part="backdrop"]:not([open]) {
+          display: none;
         }
 
         [part="sheet"] {
@@ -183,6 +206,7 @@ export class ShortcutsOverlay extends BaseElement {
         return ["commands", "heading", "hotkey", "open"];
     }
     hostEl;
+    backdropEl = null;
     focusRestore = new FocusRestore();
     wasOpen = false;
     commandsRaw = null;
@@ -333,6 +357,9 @@ export class ShortcutsOverlay extends BaseElement {
         }
         if (!this.open) {
             const wasOpen = this.wasOpen;
+            // Leave the top layer before the element is discarded, not after.
+            dismissModal(this.backdropEl);
+            this.backdropEl = null;
             this.hostEl.innerHTML = "";
             this.wasOpen = false;
             if (wasOpen) {
@@ -365,8 +392,8 @@ export class ShortcutsOverlay extends BaseElement {
         })
             .join("");
         this.hostEl.innerHTML = `
-      <div part="backdrop">
-        <div part="sheet" role="dialog" aria-modal="true" aria-label="${escapeHtml(this.heading)}">
+      <dialog part="backdrop" aria-label="Keyboard shortcuts">
+        <div part="sheet">
           <div part="header">
             <h2 part="title">${escapeHtml(this.heading)}</h2>
             <button type="button" part="close">Close</button>
@@ -375,8 +402,18 @@ export class ShortcutsOverlay extends BaseElement {
             ? `<ul part="groups" role="list">${sections}</ul>`
             : `<div part="empty">No keyboard shortcuts are defined.</div>`}
         </div>
-      </div>
+      </dialog>
     `;
+        this.backdropEl = this.hostEl.querySelector('[part="backdrop"]');
+        if (this.backdropEl) {
+            // A modal dialog closes itself on Escape and fires `cancel`; route it
+            // through the component's own dismissal so state stays in sync.
+            this.backdropEl.addEventListener("cancel", event => {
+                event.preventDefault();
+                this.dismiss();
+            });
+        }
+        promoteModal(this.backdropEl);
         if (justOpened) {
             this.hostEl.querySelector('[part="close"]')?.focus();
         }

package/dist/components/overlays/tooltip.js

@@ -1,4 +1,5 @@
 import { BaseElement } from "../../core/index.js";
+import { dismissPopover, promotePopover } from "../../foundations/overlay/index.js";
 import { boeRadius } from "../../foundations/geometry/index.js";
 import { boeNeutralInteractiveStyles } from "../../foundations/tokens/index.js";
 import { parsePlacement, trackAnchor, } from "../../foundations/overlay/index.js";
@@ -40,7 +41,12 @@ const tooltipStyles = `
 
   /* Positioned by JS (foundations/overlay) as position: fixed, so it escapes
      ancestor overflow and flips/shifts to stay in the viewport. */
+  /* display is stated explicitly because the element carries
+     popover="manual": the UA sheet hides a popover that is not open, and an
+     author declaration outranks it. If showPopover() is unavailable or fails,
+     this still renders as before and only the top layer is lost. */
   [part="tooltip"] {
+    display: block;
     position: fixed;
     inset-block-start: 0;
     inset-inline-start: 0;
@@ -180,7 +186,7 @@ export class Tooltip extends BaseElement {
         <span part="trigger-host">
           <slot><button type="button" part="trigger">?</button></slot>
         </span>
-        <div id="${this.tooltipId}" part="tooltip" role="tooltip" hidden><span part="label"></span><slot name="content"></slot></div>
+        <div id="${this.tooltipId}" part="tooltip" popover="manual" role="tooltip" hidden><span part="label"></span><slot name="content"></slot></div>
       </span>
     `;
         this.triggerHostEl = this.shadowRoot.querySelector('[part="trigger-host"]');
@@ -232,6 +238,14 @@ export class Tooltip extends BaseElement {
             this.tooltipEl.setAttribute("data-theme", theme);
         }
         this.tooltipEl.hidden = !this.openValue;
+        // Top layer keeps it above the page even inside an ancestor with a
+        // transform/filter/contain, which position:fixed alone cannot escape.
+        if (this.openValue) {
+            promotePopover(this.tooltipEl);
+        }
+        else {
+            dismissPopover(this.tooltipEl);
+        }
         const trigger = this.resolveDescribedTrigger();
         if (trigger === this.fallbackTriggerEl) {
             this.fallbackTriggerEl.setAttribute("aria-label", this.triggerLabel);

package/dist/foundations/overlay/index.d.ts

@@ -1,2 +1,3 @@
 export { anchorFloating, parsePlacement, resolvePosition, trackAnchor, } from "./positioning.js";
+export { dismissModal, dismissPopover, promoteModal, promotePopover, } from "./top-layer.js";
 export type { OverlayAlign, OverlayPlacement, OverlaySide, PositionOptions, PositionResult, Rect, Size, } from "./positioning.js";

package/dist/foundations/overlay/index.js

@@ -1 +1,2 @@
 export { anchorFloating, parsePlacement, resolvePosition, trackAnchor, } from "./positioning.js";
+export { dismissModal, dismissPopover, promoteModal, promotePopover, } from "./top-layer.js";

package/dist/foundations/overlay/top-layer.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Top-layer promotion for overlays.
+ *
+ * An overlay has to paint above the page, and `position: fixed` alone cannot
+ * promise that: an ancestor with a `transform`, `filter`, `perspective`,
+ * `contain`, or `will-change` becomes the containing block, and the overlay is
+ * positioned — and clipped — against that ancestor instead of the viewport.
+ *
+ * The old answer was to move the overlay's host node to `document.body`.
+ * `box-drawer` did exactly that and it broke every framework that owns the
+ * node: React unmounting a tree containing an open drawer threw
+ * `NotFoundError`, because the node it tried to remove was no longer its child.
+ *
+ * The top layer solves the same problem without touching the DOM tree. It is a
+ * rendering concern, so the host stays exactly where its framework put it.
+ *
+ * Two primitives, and the difference is modality rather than taste:
+ *
+ * - `showModal()` on a `<dialog>` — for overlays that own the screen while they
+ *   are up, with a scrim, a focus trap, and the rest of the page inert.
+ * - `showPopover()` on a `[popover]` element — for anchored, non-modal surfaces
+ *   (tooltips, menus, popovers) that must **not** trap focus or block the page.
+ *
+ * Using the modal primitive for an anchored surface would be a behaviour
+ * regression, not just an overreach, which is why these are separate calls.
+ *
+ * Every entry point is guarded rather than assumed. jsdom implements neither
+ * API, so the unit suite exercises everything around the promotion and the
+ * promotion itself is verified in a browser; and a detached or hidden element
+ * throws rather than opening, which is a normal state during teardown.
+ */
+/** An element that may be promotable as a modal dialog. */
+type MaybeDialog = HTMLElement & {
+    showModal?: () => void;
+    close?: () => void;
+    open?: boolean;
+};
+/** An element that may be promotable as a popover. */
+type MaybePopover = HTMLElement & {
+    showPopover?: () => void;
+    hidePopover?: () => void;
+};
+/**
+ * Promote a `<dialog>` into the top layer as a modal.
+ *
+ * Returns whether the promotion happened, so a caller can tell "not supported
+ * here" from "already open" if it needs to — most do not.
+ */
+export declare const promoteModal: (element: MaybeDialog | null) => boolean;
+/** Close a modal `<dialog>`, leaving the top layer. */
+export declare const dismissModal: (element: MaybeDialog | null) => void;
+/**
+ * Promote an element into the top layer as a **non-modal** popover.
+ *
+ * Callers are expected to set `popover="manual"` on the element: `auto`
+ * popovers light-dismiss and close each other, which fights components that
+ * already own their own dismissal rules.
+ */
+export declare const promotePopover: (element: MaybePopover | null) => boolean;
+/** Hide a popover, leaving the top layer. */
+export declare const dismissPopover: (element: MaybePopover | null) => void;
+export {};

package/dist/foundations/overlay/top-layer.js

@@ -0,0 +1,95 @@
+/**
+ * Top-layer promotion for overlays.
+ *
+ * An overlay has to paint above the page, and `position: fixed` alone cannot
+ * promise that: an ancestor with a `transform`, `filter`, `perspective`,
+ * `contain`, or `will-change` becomes the containing block, and the overlay is
+ * positioned — and clipped — against that ancestor instead of the viewport.
+ *
+ * The old answer was to move the overlay's host node to `document.body`.
+ * `box-drawer` did exactly that and it broke every framework that owns the
+ * node: React unmounting a tree containing an open drawer threw
+ * `NotFoundError`, because the node it tried to remove was no longer its child.
+ *
+ * The top layer solves the same problem without touching the DOM tree. It is a
+ * rendering concern, so the host stays exactly where its framework put it.
+ *
+ * Two primitives, and the difference is modality rather than taste:
+ *
+ * - `showModal()` on a `<dialog>` — for overlays that own the screen while they
+ *   are up, with a scrim, a focus trap, and the rest of the page inert.
+ * - `showPopover()` on a `[popover]` element — for anchored, non-modal surfaces
+ *   (tooltips, menus, popovers) that must **not** trap focus or block the page.
+ *
+ * Using the modal primitive for an anchored surface would be a behaviour
+ * regression, not just an overreach, which is why these are separate calls.
+ *
+ * Every entry point is guarded rather than assumed. jsdom implements neither
+ * API, so the unit suite exercises everything around the promotion and the
+ * promotion itself is verified in a browser; and a detached or hidden element
+ * throws rather than opening, which is a normal state during teardown.
+ */
+/**
+ * Promote a `<dialog>` into the top layer as a modal.
+ *
+ * Returns whether the promotion happened, so a caller can tell "not supported
+ * here" from "already open" if it needs to — most do not.
+ */
+export const promoteModal = (element) => {
+    if (!element || typeof element.showModal !== "function" || element.open) {
+        return false;
+    }
+    try {
+        element.showModal();
+        return true;
+    }
+    catch {
+        // Detached, hidden, or already promoted by another path. The overlay still
+        // renders and behaves; it simply does not get the top layer.
+        return false;
+    }
+};
+/** Close a modal `<dialog>`, leaving the top layer. */
+export const dismissModal = (element) => {
+    if (!element || typeof element.close !== "function" || !element.open) {
+        return;
+    }
+    try {
+        element.close();
+    }
+    catch {
+        // Already closed or detached; nothing to undo.
+    }
+};
+/**
+ * Promote an element into the top layer as a **non-modal** popover.
+ *
+ * Callers are expected to set `popover="manual"` on the element: `auto`
+ * popovers light-dismiss and close each other, which fights components that
+ * already own their own dismissal rules.
+ */
+export const promotePopover = (element) => {
+    if (!element || typeof element.showPopover !== "function") {
+        return false;
+    }
+    try {
+        element.showPopover();
+        return true;
+    }
+    catch {
+        // Throws if already showing, or if the element is not connected.
+        return false;
+    }
+};
+/** Hide a popover, leaving the top layer. */
+export const dismissPopover = (element) => {
+    if (!element || typeof element.hidePopover !== "function") {
+        return;
+    }
+    try {
+        element.hidePopover();
+    }
+    catch {
+        // Not currently showing; nothing to undo.
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unofficialbox/box-open-elements",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Box Open Elements: an open, framework-agnostic design system and web component library for Box-style experiences",
   "license": "MIT",
   "homepage": "https://unofficialbox.github.io/box-open-elements",