@unofficialbox/box-open-elements 0.2.0 → 0.3.0

package/dist/components/navigation/tabs.js

@@ -1,5 +1,5 @@
 import { BaseElement } from "../../core/index.js";
-import { boeControl, boeSpace } from "../../foundations/geometry/index.js";
+import { boeControl, boeRadius, boeSpace } from "../../foundations/geometry/index.js";
 import { boeFocusVisibleStyles, } from "../../foundations/tokens/index.js";
 import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
 const DEFAULT_TAG_NAME = "box-tabs";
@@ -88,6 +88,22 @@ const tabsStyles = `
     outline-offset: -2px;
     box-shadow: none;
   }
+
+  /* Panels carry no default padding — an empty panel is zero-height, and
+     consumers style their own slotted content. */
+  [part="panel"] {
+    outline: none;
+  }
+
+  [part="panel"][hidden] {
+    display: none;
+  }
+
+  [part="panel"]:focus-visible {
+    outline: 2px solid var(--boe-token-surface-surface-brand, #0061d5);
+    outline-offset: 2px;
+    border-radius: ${boeRadius.med};
+  }
 `;
 export class BoxTabsElement extends BaseElement {
     static get observedAttributes() {
@@ -96,6 +112,8 @@ export class BoxTabsElement extends BaseElement {
     valueInternal = "";
     lastOptionsJson = "";
     tabsEl;
+    panelsEl;
+    uid = `boe-tabs-${Math.random().toString(36).slice(2, 8)}`;
     get label() {
         return this.getAttribute("label") ?? "Tabs";
     }
@@ -169,17 +187,21 @@ export class BoxTabsElement extends BaseElement {
                     : index === options.length - 1
                         ? "last"
                         : "middle";
+            const selected = option.value === selectedValue;
+            const value = escapeHtml(option.value);
             return `
           <button
             type="button"
             part="tab"
             role="tab"
+            id="${this.uid}-tab-${value}"
+            aria-controls="${this.uid}-panel-${value}"
             data-layout="${this.layout}"
             data-position="${position}"
-            data-selected="${String(option.value === selectedValue)}"
-            data-value="${escapeHtml(option.value)}"
-            aria-selected="${String(option.value === selectedValue)}"
-            tabindex="${option.value === selectedValue ? "0" : "-1"}"
+            data-selected="${String(selected)}"
+            data-value="${value}"
+            aria-selected="${String(selected)}"
+            tabindex="${selected ? "0" : "-1"}"
           >
             ${escapeHtml(option.label)}
           </button>
@@ -187,6 +209,25 @@ export class BoxTabsElement extends BaseElement {
         })
             .join("");
     }
+    /** One tabpanel per option, fed by a slot named for the option value. */
+    renderPanelsMarkup(options, selectedValue) {
+        return options
+            .map(option => {
+            const value = escapeHtml(option.value);
+            const selected = option.value === selectedValue;
+            return `
+          <div
+            part="panel"
+            role="tabpanel"
+            id="${this.uid}-panel-${value}"
+            aria-labelledby="${this.uid}-tab-${value}"
+            tabindex="0"
+            ${selected ? "" : "hidden"}
+          ><slot name="${value}"></slot></div>
+        `;
+        })
+            .join("");
+    }
     renderTemplate() {
         if (!this.shadowRoot) {
             return;
@@ -194,8 +235,10 @@ export class BoxTabsElement extends BaseElement {
         this.shadowRoot.innerHTML = `
       <style>${tabsStyles}</style>
       <div part="tabs" role="tablist"></div>
+      <div part="panels"></div>
     `;
         this.tabsEl = this.shadowRoot.querySelector('[part="tabs"]');
+        this.panelsEl = this.shadowRoot.querySelector('[part="panels"]');
     }
     setupListeners() {
         this.tabsEl.addEventListener("click", event => {
@@ -254,6 +297,7 @@ export class BoxTabsElement extends BaseElement {
         this.tabsEl.setAttribute("aria-label", this.label);
         if (optionsJson !== this.lastOptionsJson) {
             this.tabsEl.innerHTML = this.renderTabsMarkup(options, selectedValue);
+            this.panelsEl.innerHTML = this.renderPanelsMarkup(options, selectedValue);
             this.lastOptionsJson = optionsJson;
             return;
         }
@@ -277,6 +321,10 @@ export class BoxTabsElement extends BaseElement {
             tab.setAttribute("aria-selected", String(selected));
             tab.tabIndex = selected ? 0 : -1;
         });
+        // Show only the selected tab's panel.
+        this.panelsEl.querySelectorAll('[part="panel"]').forEach((panel, index) => {
+            panel.hidden = options[index]?.value !== selectedValue;
+        });
     }
 }
 export const defineBoxTabsElement = (tagName = DEFAULT_TAG_NAME) => {

package/dist/components/overlays/context-menu.d.ts

@@ -0,0 +1,42 @@
+import { BaseElement } from "../../core/index.js";
+export interface ContextMenuItem {
+    id: string;
+    label: string;
+    disabled?: boolean;
+    /** Render a divider *before* this item. */
+    separator?: boolean;
+}
+/**
+ * Right-click context menu — box-ui-elements `ContextMenu`. The default slot is
+ * the target area; right-clicking (or Shift+F10 / the ContextMenu key) opens a
+ * menu at the pointer, positioned with `foundations/overlay` so it stays in the
+ * viewport. Full keyboard menu: arrows, Home/End, Enter/Space, Escape.
+ */
+export declare class BoxContextMenuElement extends BaseElement {
+    static get observedAttributes(): string[];
+    private openValue;
+    private targetEl;
+    private surfaceEl;
+    private readonly focusRestore;
+    private documentBound;
+    private readonly onOutside;
+    private readonly onReposition;
+    get items(): ContextMenuItem[];
+    set items(value: ContextMenuItem[]);
+    get disabled(): boolean;
+    set disabled(value: boolean);
+    get open(): boolean;
+    disconnectedCallback(): void;
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    private enabledItems;
+    private onMenuKeydown;
+    private openAt;
+    close(): void;
+    private selectItem;
+    private renderItems;
+    private bindDocument;
+    private unbindDocument;
+    protected update(): void;
+}
+export declare const defineBoxContextMenuElement: (tagName?: string) => typeof BoxContextMenuElement;

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

@@ -0,0 +1,260 @@
+import { BaseElement } from "../../core/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";
+const DEFAULT_TAG_NAME = "box-context-menu";
+const escapeHtml = (value) => value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+const contextMenuStyles = `
+  :host {
+    display: inline-block;
+    color: inherit;
+    font: inherit;
+  }
+
+  [part="target"] {
+    display: contents;
+  }
+
+  [part="surface"] {
+    position: fixed;
+    z-index: 40;
+    inset-block-start: 0;
+    inset-inline-start: 0;
+    min-width: 180px;
+    max-width: min(320px, 90vw);
+    margin: 0;
+    padding: ${boeSpace[1]};
+    border: ${boeOverlay.border};
+    border-radius: ${boeOverlay.radius};
+    background: var(--boe-token-surface-surface, #ffffff);
+    box-shadow: ${boeOverlay.shadow};
+    display: grid;
+    gap: 1px;
+  }
+
+  [part="surface"][hidden] {
+    display: none;
+  }
+
+  [part="item"] {
+    appearance: none;
+    border: none;
+    background: none;
+    font: inherit;
+    text-align: start;
+    width: 100%;
+    min-height: ${boeOverlay.itemMinHeight};
+    padding: ${boeSpace[1]} ${boeSpace[3]};
+    border-radius: ${boeOverlay.itemRadius};
+    color: var(--boe-token-text-text, #222222);
+    cursor: pointer;
+  }
+
+  [part="item"]:hover:not(:disabled),
+  [part="item"]:focus-visible {
+    background: var(--boe-token-surface-surface-secondary, #f4f4f4);
+    outline: none;
+  }
+
+  [part="item"]:focus-visible {
+    box-shadow: inset 0 0 0 2px var(--boe-token-surface-surface-brand, #0061d5);
+  }
+
+  [part="item"]:disabled {
+    opacity: 0.4;
+    cursor: not-allowed;
+  }
+
+  [part="divider"] {
+    height: 1px;
+    margin: ${boeSpace[1]} 0;
+    background: var(--boe-token-stroke-stroke, #e8e8e8);
+    border-radius: ${boeRadius.size};
+  }
+`;
+/**
+ * Right-click context menu — box-ui-elements `ContextMenu`. The default slot is
+ * the target area; right-clicking (or Shift+F10 / the ContextMenu key) opens a
+ * menu at the pointer, positioned with `foundations/overlay` so it stays in the
+ * viewport. Full keyboard menu: arrows, Home/End, Enter/Space, Escape.
+ */
+export class BoxContextMenuElement extends BaseElement {
+    static get observedAttributes() {
+        return ["items", "disabled"];
+    }
+    openValue = false;
+    targetEl;
+    surfaceEl;
+    focusRestore = new FocusRestore();
+    documentBound = false;
+    onOutside = (event) => {
+        if (!this.openValue)
+            return;
+        const path = typeof event.composedPath === "function" ? event.composedPath() : [];
+        if (!path.some(node => node === this.surfaceEl))
+            this.close();
+    };
+    onReposition = () => {
+        if (this.openValue)
+            this.close();
+    };
+    get items() {
+        const raw = this.getAttribute("items");
+        if (!raw)
+            return [];
+        try {
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    set items(value) {
+        this.setAttribute("items", JSON.stringify(value));
+    }
+    get disabled() {
+        return this.hasAttribute("disabled");
+    }
+    set disabled(value) {
+        this.toggleAttribute("disabled", Boolean(value));
+    }
+    get open() {
+        return this.openValue;
+    }
+    disconnectedCallback() {
+        this.unbindDocument();
+    }
+    renderTemplate() {
+        if (!this.shadowRoot)
+            return;
+        this.shadowRoot.innerHTML = `
+      <style>${contextMenuStyles}</style>
+      <div part="target"><slot></slot></div>
+      <div part="surface" role="menu" hidden></div>
+    `;
+        this.targetEl = this.shadowRoot.querySelector('[part="target"]');
+        this.surfaceEl = this.shadowRoot.querySelector('[part="surface"]');
+    }
+    setupListeners() {
+        this.addEventListener("contextmenu", event => {
+            if (this.disabled || this.items.length === 0)
+                return;
+            event.preventDefault();
+            this.openAt(event.clientX, event.clientY);
+        });
+        // Keyboard opener: Shift+F10 or the ContextMenu key on the focused target.
+        this.addEventListener("keydown", event => {
+            if (this.disabled)
+                return;
+            const isOpener = event.key === "ContextMenu" || (event.shiftKey && event.key === "F10");
+            if (isOpener && this.items.length) {
+                event.preventDefault();
+                const rect = this.getBoundingClientRect();
+                this.openAt(rect.left, rect.bottom);
+            }
+        });
+        this.surfaceEl.addEventListener("click", event => {
+            const item = event.target.closest('[part="item"]');
+            if (!item || item.disabled)
+                return;
+            this.selectItem(item.dataset.id ?? "");
+        });
+        this.surfaceEl.addEventListener("keydown", event => this.onMenuKeydown(event));
+    }
+    enabledItems() {
+        return Array.from(this.surfaceEl.querySelectorAll('[part="item"]:not(:disabled)'));
+    }
+    onMenuKeydown(event) {
+        if (event.key === "Escape") {
+            event.preventDefault();
+            this.close();
+            return;
+        }
+        const items = this.enabledItems();
+        if (items.length === 0)
+            return;
+        const current = items.indexOf(event.target);
+        if (event.key === "Enter" || event.key === " ") {
+            event.preventDefault();
+            event.target.click();
+            return;
+        }
+        const next = nextRovingIndex(event.key, Math.max(current, 0), items.length, { orientation: "vertical" });
+        if (next !== null && next !== current) {
+            event.preventDefault();
+            items[next].focus();
+        }
+    }
+    openAt(clientX, clientY) {
+        this.renderItems();
+        this.surfaceEl.hidden = false;
+        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`;
+        this.surfaceEl.style.top = `${Math.round(y)}px`;
+        this.openValue = true;
+        this.bindDocument();
+        this.dispatchEvent(new CustomEvent("open-changed", { bubbles: true, composed: true, detail: { open: true } }));
+        this.focusRestore.capture(document.activeElement);
+        queueMicrotask(() => this.enabledItems()[0]?.focus());
+    }
+    close() {
+        if (!this.openValue)
+            return;
+        this.openValue = false;
+        this.surfaceEl.hidden = true;
+        this.unbindDocument();
+        this.dispatchEvent(new CustomEvent("open-changed", { bubbles: true, composed: true, detail: { open: false } }));
+        this.focusRestore.restore();
+    }
+    selectItem(id) {
+        const item = this.items.find(entry => entry.id === id);
+        if (!item || item.disabled)
+            return;
+        this.dispatchEvent(new CustomEvent("item-selected", { bubbles: true, composed: true, detail: item }));
+        this.close();
+    }
+    renderItems() {
+        this.surfaceEl.innerHTML = this.items
+            .map(item => {
+            const divider = item.separator ? `<div part="divider" role="separator"></div>` : "";
+            const disabled = item.disabled ? " disabled" : "";
+            return `${divider}<button type="button" part="item" role="menuitem" data-id="${escapeHtml(item.id)}"${disabled}>${escapeHtml(item.label)}</button>`;
+        })
+            .join("");
+    }
+    bindDocument() {
+        if (this.documentBound)
+            return;
+        document.addEventListener("pointerdown", this.onOutside, true);
+        document.addEventListener("scroll", this.onReposition, true);
+        window.addEventListener("resize", this.onReposition);
+        this.documentBound = true;
+    }
+    unbindDocument() {
+        if (!this.documentBound)
+            return;
+        document.removeEventListener("pointerdown", this.onOutside, true);
+        document.removeEventListener("scroll", this.onReposition, true);
+        window.removeEventListener("resize", this.onReposition);
+        this.documentBound = false;
+    }
+    update() {
+        // The menu content is rendered on open; nothing to sync while closed.
+        if (this.openValue)
+            this.renderItems();
+    }
+}
+export const defineBoxContextMenuElement = (tagName = DEFAULT_TAG_NAME) => {
+    const existingElement = customElements.get(tagName);
+    if (existingElement) {
+        return existingElement;
+    }
+    customElements.define(tagName, BoxContextMenuElement);
+    return BoxContextMenuElement;
+};

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

@@ -3,6 +3,8 @@ export declare class BoxDialogElement extends BaseElement {
     static get observedAttributes(): string[];
     private openValue;
     private wasOpen;
+    private scrollLocked;
+    private previousBodyOverflow;
     private hostEl;
     private titleEl;
     private descriptionEl;
@@ -16,6 +18,12 @@ export declare class BoxDialogElement extends BaseElement {
     set description(value: string);
     get confirmLabel(): string;
     set confirmLabel(value: string);
+    /** Modal size — box-ui-elements Modal sizes. Default `medium`. */
+    get size(): "small" | "medium" | "large" | "fullscreen";
+    set size(value: "small" | "medium" | "large" | "fullscreen");
+    /** Lock/unlock background page scroll while the modal is open. */
+    private setScrollLock;
+    disconnectedCallback(): void;
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     show(): void;
     close(): void;

package/dist/components/overlays/dialog.js

@@ -31,6 +31,16 @@ const dialogStyles = `
     color: var(--boe-token-text-text, #222222);
   }
 
+  /* Size options — box-ui-elements Modal sizes. Default (medium) is the base. */
+  [part="dialog"][data-size="small"] { width: min(380px, calc(100vw - 3rem)); }
+  [part="dialog"][data-size="large"] { width: min(760px, calc(100vw - 3rem)); }
+  [part="dialog"][data-size="fullscreen"] {
+    width: calc(100vw - 2rem);
+    height: calc(100vh - 2rem);
+    max-width: none;
+    border-radius: ${boeRadius.large};
+  }
+
   [part="header"] h2 {
     margin: 0;
     font: inherit;
@@ -96,10 +106,12 @@ const dialogStyles = `
 `;
 export class BoxDialogElement extends BaseElement {
     static get observedAttributes() {
-        return ["confirm-label", "description", "heading", "open"];
+        return ["confirm-label", "description", "heading", "open", "size"];
     }
     openValue = false;
     wasOpen = false;
+    scrollLocked = false;
+    previousBodyOverflow = "";
     hostEl;
     titleEl = null;
     descriptionEl = null;
@@ -140,6 +152,31 @@ export class BoxDialogElement extends BaseElement {
     set confirmLabel(value) {
         this.setAttribute("confirm-label", value);
     }
+    /** Modal size — box-ui-elements Modal sizes. Default `medium`. */
+    get size() {
+        const size = this.getAttribute("size");
+        return size === "small" || size === "large" || size === "fullscreen" ? size : "medium";
+    }
+    set size(value) {
+        this.setAttribute("size", value);
+    }
+    /** Lock/unlock background page scroll while the modal is open. */
+    setScrollLock(locked) {
+        if (locked === this.scrollLocked) {
+            return;
+        }
+        this.scrollLocked = locked;
+        if (locked) {
+            this.previousBodyOverflow = document.body.style.overflow;
+            document.body.style.overflow = "hidden";
+        }
+        else {
+            document.body.style.overflow = this.previousBodyOverflow;
+        }
+    }
+    disconnectedCallback() {
+        this.setScrollLock(false);
+    }
     attributeChangedCallback(name, oldValue, newValue) {
         if (name === "open") {
             this.openValue = this.hasAttribute("open");
@@ -203,6 +240,7 @@ export class BoxDialogElement extends BaseElement {
         }
         if (!this.openValue) {
             const wasOpen = this.wasOpen;
+            this.setScrollLock(false);
             this.hostEl.innerHTML = "";
             this.titleEl = null;
             this.descriptionEl = null;
@@ -218,11 +256,12 @@ export class BoxDialogElement extends BaseElement {
         if (justOpened) {
             this.focusRestore.capture();
         }
+        this.setScrollLock(true);
         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">
+          <section part="dialog" role="dialog" aria-modal="true" tabindex="-1" aria-labelledby="dialog-title" data-size="${this.size}">
             <header part="header">
               <h2 id="dialog-title"></h2>
             </header>
@@ -239,6 +278,10 @@ export class BoxDialogElement extends BaseElement {
         this.titleEl = this.hostEl.querySelector("#dialog-title");
         this.descriptionEl = this.hostEl.querySelector('[part="description"]');
         this.confirmEl = this.hostEl.querySelector('[part="confirm"]');
+        const dialogEl = this.hostEl.querySelector('[part="dialog"]');
+        if (dialogEl) {
+            dialogEl.dataset.size = this.size;
+        }
         if (this.titleEl) {
             this.titleEl.textContent = this.heading;
         }

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

@@ -1,5 +1,9 @@
 import { BaseElement } from "../../core/index.js";
-export type PopoverPlacement = "bottom" | "top" | "start" | "end";
+/**
+ * Any side (`top`/`bottom`/`left`/`right`) with optional `-start`/`-center`/`-end`
+ * alignment, plus the legacy names (`start` = left, `end` = right).
+ */
+export type PopoverPlacement = "top" | "bottom" | "left" | "right" | "start" | "end" | "top-start" | "top-center" | "top-end" | "bottom-start" | "bottom-center" | "bottom-end" | "left-start" | "left-center" | "left-end" | "right-start" | "right-center" | "right-end";
 export declare class BoxPopoverElement extends BaseElement {
     static get observedAttributes(): string[];
     private openValue;
@@ -7,6 +11,7 @@ export declare class BoxPopoverElement extends BaseElement {
     private documentListenersBound;
     private triggerEl;
     private surfaceEl;
+    private positionCleanup;
     private readonly focusRestore;
     private readonly onDocumentKeydown;
     private readonly onOutsidePointer;
@@ -31,5 +36,8 @@ export declare class BoxPopoverElement extends BaseElement {
     protected renderTemplate(): void;
     protected setupListeners(): void;
     protected update(): void;
+    /** Anchor the surface to the trigger and keep it positioned while open. */
+    private startPositioning;
+    private stopPositioning;
 }
 export declare const defineBoxPopoverElement: (tagName?: string) => typeof BoxPopoverElement;

package/dist/components/overlays/popover.js

@@ -1,15 +1,17 @@
 import { BaseElement } from "../../core/index.js";
 import { FocusRestore, getTabbableElements } from "../../foundations/a11y/index.js";
-import { boeControl, boeOverlay, boeRadius, boeSpace } from "../../foundations/geometry/index.js";
+import { boeControl, boeOverlay, boeRadius } from "../../foundations/geometry/index.js";
 import { boeNeutralInteractiveStyles } from "../../foundations/tokens/index.js";
 import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
+import { parsePlacement, trackAnchor, } from "../../foundations/overlay/index.js";
 const DEFAULT_TAG_NAME = "box-popover";
+/** The attribute value if it names a valid placement, else `"bottom"`. */
 const resolvePlacement = (value) => {
-    if (value === "top" || value === "start" || value === "end" || value === "bottom") {
-        return value;
-    }
+    if (value && parsePlacement(value))
+        return value.trim().toLowerCase();
     return "bottom";
 };
+const OVERLAY_OFFSET = 4;
 const popoverStyles = `
   :host {
     display: inline-block;
@@ -46,10 +48,13 @@ const popoverStyles = `
 
   ${boeNeutralInteractiveStyles('[part="trigger"]')}
 
+  /* 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. */
   [part="surface"] {
-    position: absolute;
+    position: fixed;
     z-index: 30;
-    inset-block-start: calc(100% + ${boeSpace[1]});
+    inset-block-start: 0;
     inset-inline-start: 0;
     width: min(360px, calc(100vw - 5rem));
     min-width: 200px;
@@ -62,22 +67,6 @@ const popoverStyles = `
     line-height: 1.5;
   }
 
-  :host([placement="top"]) [part="surface"] {
-    inset-block-start: auto;
-    inset-block-end: calc(100% + ${boeSpace[1]});
-  }
-
-  :host([placement="start"]) [part="surface"] {
-    inset-block-start: 0;
-    inset-inline-start: auto;
-    inset-inline-end: calc(100% + ${boeSpace[1]});
-  }
-
-  :host([placement="end"]) [part="surface"] {
-    inset-block-start: 0;
-    inset-inline-start: calc(100% + ${boeSpace[1]});
-  }
-
   [part="surface"][hidden] {
     display: none;
   }
@@ -91,6 +80,7 @@ export class BoxPopoverElement extends BaseElement {
     documentListenersBound = false;
     triggerEl;
     surfaceEl;
+    positionCleanup = null;
     focusRestore = new FocusRestore();
     onDocumentKeydown = (event) => {
         if (!this.openValue || event.key !== "Escape") {
@@ -164,6 +154,7 @@ export class BoxPopoverElement extends BaseElement {
     }
     disconnectedCallback() {
         this.unbindDocumentListeners();
+        this.stopPositioning();
     }
     attributeChangedCallback(name, oldValue, newValue) {
         if (name === "open") {
@@ -297,6 +288,12 @@ export class BoxPopoverElement extends BaseElement {
         const justClosed = !this.openValue && this.wasOpen;
         this.surfaceEl.hidden = !this.openValue;
         this.syncDocumentListeners();
+        if (this.openValue) {
+            this.startPositioning();
+        }
+        else {
+            this.stopPositioning();
+        }
         if (justOpened) {
             this.focusRestore.capture(this.triggerEl);
             queueMicrotask(() => this.focusSurface());
@@ -306,6 +303,24 @@ export class BoxPopoverElement extends BaseElement {
         }
         this.wasOpen = this.openValue;
     }
+    /** Anchor the surface to the trigger and keep it positioned while open. */
+    startPositioning() {
+        if (this.positionCleanup) {
+            return;
+        }
+        const placement = parsePlacement(this.getAttribute("placement")) ?? { side: "bottom", align: "start" };
+        this.positionCleanup = trackAnchor(this.triggerEl, this.surfaceEl, {
+            placement,
+            offset: OVERLAY_OFFSET,
+        });
+    }
+    stopPositioning() {
+        this.positionCleanup?.();
+        this.positionCleanup = null;
+        this.surfaceEl.style.left = "";
+        this.surfaceEl.style.top = "";
+        this.surfaceEl.style.margin = "";
+    }
 }
 export const defineBoxPopoverElement = (tagName = DEFAULT_TAG_NAME) => {
     const existingElement = customElements.get(tagName);