@unofficialbox/box-open-elements 0.9.0 → 0.11.0

package/dist/components/feedback/tone.js

@@ -0,0 +1,31 @@
+/**
+ * The status vocabulary shared by the feedback surfaces.
+ *
+ * `box-alert` and `box-toast` both state their tone in words for screen
+ * readers, and both must say the *same* words: a reader who hears "In progress"
+ * from an alert should not hear "Inprogress" from a toast reporting the same
+ * thing. One definition is what keeps them in step.
+ */
+/**
+ * The tone as a word, for assistive technology.
+ *
+ * Tone is otherwise carried by fill and glyph, neither of which reaches a
+ * screen reader. An unrecognised tone is title-cased rather than dropped —
+ * a host that invents a tone should still get something spoken.
+ */
+export const toneAccessibleLabel = (tone) => {
+    switch (tone) {
+        case "success":
+            return "Success";
+        case "error":
+            return "Error";
+        case "warning":
+            return "Warning";
+        case "inprogress":
+            return "In progress";
+        case "info":
+            return "Info";
+        default:
+            return tone.charAt(0).toUpperCase() + tone.slice(1);
+    }
+};

package/dist/components/layout/grid.d.ts

@@ -0,0 +1,41 @@
+import { BaseElement } from "../../core/index.js";
+/**
+ * Adobe Spectrum's responsive grid, for laying out arbitrary content.
+ *
+ * Twelve columns by default, with gutters stepping 16 → 24 → 32 → 40 → 48px
+ * across Spectrum's breakpoints. Children declare their own placement:
+ *
+ * ```html
+ * <box-grid columns="12">
+ *   <article data-span="8">Main</article>
+ *   <aside data-span="4">Sidebar</aside>
+ *   <footer data-span="6" data-offset="3">Centred</footer>
+ * </box-grid>
+ * ```
+ *
+ * Placement lives on the children rather than in a payload on the host,
+ * because the children are arbitrary content the author already writes — an
+ * `items` array would have to address them positionally and would silently
+ * mis-place everything the moment one was inserted.
+ *
+ * `data-offset` sets an explicit `grid-column-start`. That is the author's
+ * stated intent here, unlike `box-skeleton`, which generates its own regions
+ * and uses spacers so auto-placement is not disturbed.
+ */
+export declare class Grid extends BaseElement {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    private gridEl;
+    /** Columns in the grid. Defaults to Spectrum's twelve. */
+    get columns(): number;
+    set columns(value: number);
+    /**
+     * Height of one row. Unset by default: a layout grid's rows should be as
+     * tall as their content, and pinning them would crop it.
+     */
+    get rowHeight(): string;
+    set rowHeight(value: string);
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    protected update(): void;
+}

package/dist/components/layout/grid.js

@@ -0,0 +1,152 @@
+import { BaseElement } from "../../core/index.js";
+import { BOE_GRID_COLUMNS, BOE_GRID_GUTTER_PROPERTY, boeGridGutterStyles, resolveGridCount, } from "../../foundations/layout/index.js";
+const DEFAULT_TAG_NAME = "box-grid";
+/**
+ * How far a child's placement attributes are honoured.
+ *
+ * Placement is expressed in CSS rules generated per value, not computed per
+ * element, so the ceiling is a real limit rather than a guess. Twenty-four
+ * covers a twelve-column grid used at double density without emitting rules
+ * nobody will match.
+ */
+const MAX_TRACKS = 24;
+/**
+ * Placement rules, one per value.
+ *
+ * A slotted child cannot be given a computed `grid-column` without writing to
+ * the light DOM, which is the host's tree, not ours. Generating a rule per
+ * value keeps placement declarative and leaves the author's markup untouched.
+ *
+ * `grid-column-start` and `grid-column-end` are set by separate rules on
+ * purpose: they compose, so offset and span combine without needing a rule for
+ * every offset × span pair.
+ */
+const placementRules = () => {
+    const rules = [];
+    for (let value = 1; value <= MAX_TRACKS; value += 1) {
+        rules.push(`  ::slotted([data-span="${value}"]) { grid-column-end: span ${value}; }`);
+        rules.push(`  ::slotted([data-row-span="${value}"]) { grid-row: span ${value}; }`);
+    }
+    for (let value = 1; value < MAX_TRACKS; value += 1) {
+        // An offset of N starts the region at column N + 1.
+        rules.push(`  ::slotted([data-offset="${value}"]) { grid-column-start: ${value + 1}; }`);
+    }
+    return rules.join("\n");
+};
+const elementStyles = `
+  :host {
+    display: block;
+    color: inherit;
+    font: inherit;
+  }
+
+  :host([hidden]) {
+    display: none;
+  }
+
+${boeGridGutterStyles(":host")}
+
+  [part="grid"] {
+    display: grid;
+    grid-template-columns: repeat(var(--boe-grid-columns, ${BOE_GRID_COLUMNS}), minmax(0, 1fr));
+    gap: var(${BOE_GRID_GUTTER_PROPERTY});
+  }
+
+  /* Rows are only constrained when the author asks for them; otherwise each
+     row is as tall as its content, which is what a layout grid should do.
+     Spectrum's layout regions have no intrinsic height either — at minimum
+     they are as tall as the components inside them. */
+  :host([row-height]) [part="grid"] {
+    grid-auto-rows: var(--boe-grid-row-height);
+  }
+
+  /* Without this the slot itself is the grid item and every child lands in one
+     cell. display: contents dissolves it, so the assigned children become the
+     grid's own items. */
+  slot {
+    display: contents;
+  }
+
+  /* A region with no placement attributes occupies one column, so a bare list
+     of children reads as an even row. */
+  ::slotted(*) {
+    grid-column-end: span 1;
+  }
+
+${placementRules()}
+`;
+/**
+ * Adobe Spectrum's responsive grid, for laying out arbitrary content.
+ *
+ * Twelve columns by default, with gutters stepping 16 → 24 → 32 → 40 → 48px
+ * across Spectrum's breakpoints. Children declare their own placement:
+ *
+ * ```html
+ * <box-grid columns="12">
+ *   <article data-span="8">Main</article>
+ *   <aside data-span="4">Sidebar</aside>
+ *   <footer data-span="6" data-offset="3">Centred</footer>
+ * </box-grid>
+ * ```
+ *
+ * Placement lives on the children rather than in a payload on the host,
+ * because the children are arbitrary content the author already writes — an
+ * `items` array would have to address them positionally and would silently
+ * mis-place everything the moment one was inserted.
+ *
+ * `data-offset` sets an explicit `grid-column-start`. That is the author's
+ * stated intent here, unlike `box-skeleton`, which generates its own regions
+ * and uses spacers so auto-placement is not disturbed.
+ */
+export class Grid extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
+    static get observedAttributes() {
+        return ["columns", "row-height"];
+    }
+    gridEl;
+    /** Columns in the grid. Defaults to Spectrum's twelve. */
+    get columns() {
+        return resolveGridCount(this.getAttribute("columns"), BOE_GRID_COLUMNS);
+    }
+    set columns(value) {
+        this.setAttribute("columns", String(value));
+    }
+    /**
+     * Height of one row. Unset by default: a layout grid's rows should be as
+     * tall as their content, and pinning them would crop it.
+     */
+    get rowHeight() {
+        return this.getAttribute("row-height") ?? "";
+    }
+    set rowHeight(value) {
+        if (value) {
+            this.setAttribute("row-height", value);
+            return;
+        }
+        this.removeAttribute("row-height");
+    }
+    renderTemplate() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        this.shadowRoot.innerHTML = `<style>${elementStyles}</style><div part="grid"><slot></slot></div>`;
+        this.gridEl = this.shadowRoot.querySelector('[part="grid"]');
+    }
+    setupListeners() {
+        // Layout only: placement is declared by the children and applied in CSS.
+    }
+    update() {
+        if (!this.gridEl) {
+            return;
+        }
+        this.gridEl.style.setProperty("--boe-grid-columns", String(this.columns));
+        // Via the CSSOM rather than interpolated into markup. Note that custom
+        // properties are *not* validated the way a standard property like `width`
+        // is — they accept almost any token sequence — so this does not sanitise
+        // the value. What makes it safe is that the value never reaches an HTML
+        // string: a nonsensical one makes `grid-auto-rows` invalid at computed-value
+        // time, which falls back to `auto`, and rows simply size to their content.
+        this.gridEl.style.setProperty("--boe-grid-row-height", this.rowHeight);
+    }
+}
+Grid.register();

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

@@ -43,9 +43,7 @@ export declare class Drawer extends BaseElement {
      * `NotFoundError`, because the node it tried to remove was no longer its
      * child.
      *
-     * Guarded rather than assumed: jsdom implements neither `showModal` nor
-     * `showPopover`, so the unit suite exercises everything except the promotion
-     * itself, and that is verified in a browser.
+     * The guards live in the shared foundation, which every overlay now uses.
      */
     private promoteTopLayer;
     private dismissTopLayer;

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";
@@ -289,30 +290,13 @@ export class Drawer extends BaseElement {
      * `NotFoundError`, because the node it tried to remove was no longer its
      * child.
      *
-     * Guarded rather than assumed: jsdom implements neither `showModal` nor
-     * `showPopover`, so the unit suite exercises everything except the promotion
-     * itself, and that is verified in a browser.
+     * The guards live in the shared foundation, which every overlay now uses.
      */
     promoteTopLayer() {
-        const dialog = this.backdropEl;
-        if (!dialog || typeof dialog.showModal !== "function" || dialog.open) {
-            return;
-        }
-        // A dialog in a detached or hidden tree throws rather than opening.
-        try {
-            dialog.showModal();
-        }
-        catch {
-            // Not promotable here; the drawer still renders and behaves, it simply
-            // does not get the top layer.
-        }
+        promoteModal(this.backdropEl);
     }
     dismissTopLayer() {
-        const dialog = this.backdropEl;
-        if (!dialog || typeof dialog.close !== "function" || !dialog.open) {
-            return;
-        }
-        dialog.close();
+        dismissModal(this.backdropEl);
     }
     renderTemplate() {
         if (!this.shadowRoot) {

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;