@pure-ds/core 0.7.42 → 0.7.44

package/readme.md

@@ -469,6 +469,7 @@ Features:
 - Horizontal alignment (`.align-right` class)
 - Keyboard support (Escape to close)
 - Click-outside to close
+- Declarative close on selection via `data-dropdown-close` on clickable menu/panel items
 - Scrollable when content exceeds viewport
 - Panel can be any last child element (menu, card, form, etc.)
 

package/src/js/pds-core/pds-enhancers-meta.js

@@ -31,17 +31,22 @@ export const defaultPDSEnhancerMetadata = [
   {
     selector: "nav[data-dropdown]",
     description:
-      "Enhances a nav element with data-dropdown to toggle its last child as a dropdown panel (menu, card, form, etc.).",
+      "Enhances a nav element with data-dropdown to toggle its last child as a dropdown panel (menu, card, form, etc.). Add data-dropdown-close to any clickable descendant that should close the menu on selection.",
+    attributes: [
+      {
+        name: "data-dropdown-close",
+        description:
+          "When clicked (or when a descendant is clicked), closes the currently open dropdown popover.",
+        appliesTo: "Any clickable element inside nav[data-dropdown] menu/panel content",
+      },
+    ],
     demoHtml: `
       <nav data-dropdown>
         <button class="btn-primary">Menu</button>
-        <div class="card surface-overlay stack-sm">
-          <strong>Quick actions</strong>
-          <div class="flex gap-sm">
-            <button class="btn-primary btn-sm">Ship now</button>
-            <button class="btn-outline btn-sm">Schedule</button>
-          </div>
-        </div>
+        <menu>
+          <li><a href="#open">Open</a></li>
+          <li><a href="#settings" data-dropdown-close>Open settings and close</a></li>
+        </menu>
       </nav>
     `.trim(),
   },

package/src/js/pds-core/pds-enhancers.js

@@ -61,6 +61,11 @@ function enhanceDropdown(elem) {
     elem.querySelector("[data-dropdown-toggle]") ||
     elem.querySelector("button");
 
+  const supportsPopover =
+    typeof HTMLElement !== "undefined" &&
+    "showPopover" in HTMLElement.prototype &&
+    "hidePopover" in HTMLElement.prototype;
+
   if (trigger && !trigger.hasAttribute("type")) {
     trigger.setAttribute("type", "button");
   }
@@ -84,6 +89,19 @@ function enhanceDropdown(elem) {
     trigger.setAttribute("aria-expanded", "false");
   }
 
+  if (!supportsPopover) {
+    const warnKey = "__PDS_DROPDOWN_POPOVER_WARNED__";
+    if (!globalThis[warnKey]) {
+      globalThis[warnKey] = true;
+      console.warn(
+        "[PDS] nav[data-dropdown] requires the Popover API. Add a popover polyfill (recommended: @oddbird/popover-polyfill) for browsers without support.",
+      );
+    }
+    return;
+  }
+
+  menu.setAttribute("popover", "auto");
+
   const measureMenuSize = () => {
     const previousStyle = menu.getAttribute("style");
     menu.style.visibility = "hidden";
@@ -108,6 +126,24 @@ function enhanceDropdown(elem) {
     return { width, height };
   };
 
+  const isPopoverOpen = () => {
+    try {
+      return menu.matches(":popover-open");
+    } catch {
+      return false;
+    }
+  };
+
+  const syncClosedState = () => {
+    menu.setAttribute("aria-hidden", "true");
+    trigger?.setAttribute("aria-expanded", "false");
+  };
+
+  const syncOpenState = () => {
+    menu.setAttribute("aria-hidden", "false");
+    trigger?.setAttribute("aria-expanded", "true");
+  };
+
   const resolveDirection = () => {
     const mode = (
       elem.getAttribute("data-direction") ||
@@ -170,136 +206,23 @@ function enhanceDropdown(elem) {
   };
 
   const clearFloatingMenuPosition = () => {
-    menu.style.removeProperty("position");
-    menu.style.removeProperty("left");
-    menu.style.removeProperty("top");
-    menu.style.removeProperty("right");
-    menu.style.removeProperty("bottom");
-    menu.style.removeProperty("margin-top");
-    menu.style.removeProperty("margin-bottom");
-    menu.style.removeProperty("max-width");
-    menu.style.removeProperty("max-inline-size");
-    menu.style.removeProperty("max-height");
-    menu.style.removeProperty("overflow");
-  };
-
-  const getContainingAncestor = (node) => {
-    if (!node) return null;
-    if (node.parentElement) return node.parentElement;
-    const root = node.getRootNode?.();
-    return root instanceof ShadowRoot ? root.host : null;
-  };
-
-  const hasNonViewportFixedContainingBlock = () => {
-    let current = getContainingAncestor(menu);
-    while (current && current !== document.documentElement) {
-      const style = getComputedStyle(current);
-      const contain = style.contain || "";
-      const willChange = style.willChange || "";
-      const createsContainingBlock =
-        style.transform !== "none" ||
-        style.perspective !== "none" ||
-        style.filter !== "none" ||
-        style.backdropFilter !== "none" ||
-        contain.includes("paint") ||
-        contain.includes("layout") ||
-        contain.includes("strict") ||
-        contain.includes("content") ||
-        willChange.includes("transform") ||
-        willChange.includes("perspective") ||
-        willChange.includes("filter");
-
-      if (createsContainingBlock) {
-        return true;
-      }
-
-      current = getContainingAncestor(current);
-    }
-    return false;
-  };
-
-  const collectClippingAncestors = (startNode, stopAt = null) => {
-    const targets = [];
-    let current = getContainingAncestor(startNode);
-
-    while (current instanceof Element) {
-      const tagName = String(current.tagName || "").toUpperCase();
-      if (tagName === "HTML" || tagName === "BODY") {
-        break;
-      }
-
-      const style = getComputedStyle(current);
-      const clips = [style.overflow, style.overflowX, style.overflowY].some(
-        (value) => value && value !== "visible",
-      );
-
-      if (clips) {
-        targets.push(current);
-      }
-
-      if (stopAt && current === stopAt) {
-        break;
-      }
-
-      current = getContainingAncestor(current);
-    }
-
-    return targets;
+    [
+      "position",
+      "left",
+      "top",
+      "right",
+      "bottom",
+      "margin-top",
+      "margin-bottom",
+      "max-width",
+      "max-inline-size",
+      "max-height",
+      "overflow",
+    ].forEach((prop) => menu.style.removeProperty(prop));
   };
-
-  const setOverlayClippingOverride = (enabled, stopAt = null) => {
-    if (enabled) {
-      if (overlayOverflowOverrides.size) return;
-
-      const targets = collectClippingAncestors(menu, stopAt);
-      targets.forEach((element) => {
-        overlayOverflowOverrides.set(element, {
-          overflow: element.style.overflow,
-          overflowX: element.style.overflowX,
-          overflowY: element.style.overflowY,
-        });
-
-        element.style.overflow = "visible";
-        element.style.overflowX = "visible";
-        element.style.overflowY = "visible";
-      });
-
-      return;
-    }
-
-    overlayOverflowOverrides.forEach((previous, element) => {
-      element.style.overflow = previous.overflow;
-      element.style.overflowX = previous.overflowX;
-      element.style.overflowY = previous.overflowY;
-    });
-
-    overlayOverflowOverrides.clear();
-  };
-
-  const reattachFloatingMenu = () => {
-    if (menu.getAttribute("aria-hidden") !== "false") return;
-    clearFloatingMenuPosition();
-    requestAnimationFrame(() => {
-      requestAnimationFrame(() => {
-        positionFloatingMenu();
-      });
-    });
-  };
-
-  const positionFloatingMenu = () => {
-    if (menu.getAttribute("aria-hidden") !== "false") return;
-    const hasFixedContainingBlock = hasNonViewportFixedContainingBlock();
-
-    if (hasFixedContainingBlock) {
-      // Fixed overlay is unsafe in this context; keep local positioning,
-      // but temporarily unclip ancestor overflow containers.
-      setOverlayClippingOverride(true);
-      clearFloatingMenuPosition();
-      return;
-    }
-
-    // Fixed overlay path does not need clipping overrides.
-    setOverlayClippingOverride(false);
+  
+  const positionPopoverMenu = () => {
+    if (!isPopoverOpen()) return;
 
     const anchorRect = (trigger || elem).getBoundingClientRect();
     const viewport = window.visualViewport;
@@ -350,19 +273,21 @@ function enhanceDropdown(elem) {
       ),
     );
 
-    menu.style.position = "fixed";
-    menu.style.left = `${Math.round(left)}px`;
-    menu.style.top = `${Math.round(top)}px`;
-    menu.style.right = "auto";
-    menu.style.bottom = "auto";
-    menu.style.marginTop = "0";
-    menu.style.marginBottom = "0";
+    Object.assign(menu.style, {
+      position: "fixed",
+      left: `${Math.round(left)}px`,
+      top: `${Math.round(top)}px`,
+      right: "auto",
+      bottom: "auto",
+      marginTop: "0",
+      marginBottom: "0",
+    });
   };
 
   let repositionHandler = null;
   const bindReposition = () => {
     if (repositionHandler) return;
-    repositionHandler = () => positionFloatingMenu();
+    repositionHandler = () => positionPopoverMenu();
     window.addEventListener("resize", repositionHandler);
     window.addEventListener("scroll", repositionHandler, true);
   };
@@ -376,11 +301,10 @@ function enhanceDropdown(elem) {
 
   let configChangedHandler = null;
   let configRepositionFrame = null;
-  const overlayOverflowOverrides = new Map();
   const bindConfigChanged = () => {
     if (configChangedHandler || typeof document === "undefined") return;
     configChangedHandler = () => {
-      if (menu.getAttribute("aria-hidden") !== "false") return;
+      if (!isPopoverOpen()) return;
       elem.dataset.dropdownDirection = resolveDirection();
       elem.dataset.dropdownAlign = resolveAlign();
 
@@ -389,8 +313,8 @@ function enhanceDropdown(elem) {
       }
       configRepositionFrame = requestAnimationFrame(() => {
         configRepositionFrame = null;
-        if (menu.getAttribute("aria-hidden") !== "false") return;
-        positionFloatingMenu();
+        if (!isPopoverOpen()) return;
+        positionPopoverMenu();
       });
     };
     document.addEventListener("pds:config-changed", configChangedHandler);
@@ -406,60 +330,54 @@ function enhanceDropdown(elem) {
     }
   };
 
-  // Store click handler reference for cleanup
-  let clickHandler = null;
+  menu.addEventListener("toggle", (event) => {
+    const isOpen = event.newState === "open";
 
-  const openMenu = () => {
-    setOverlayClippingOverride(false);
-    elem.dataset.dropdownDirection = resolveDirection();
-    elem.dataset.dropdownAlign = resolveAlign();
-    menu.setAttribute("aria-hidden", "false");
-    trigger?.setAttribute("aria-expanded", "true");
-    bindReposition();
-    bindConfigChanged();
-    reattachFloatingMenu();
-
-    // Add click-outside handler when opening
-    if (!clickHandler) {
-      clickHandler = (event) => {
-        // Use composedPath() to handle Shadow DOM
-        const path = event.composedPath ? event.composedPath() : [event.target];
-        const clickedInside = path.some((node) => node === elem);
-
-        if (!clickedInside) {
-          closeMenu();
-        }
-      };
-      // Use a slight delay to avoid closing immediately if this was triggered by a click
-      setTimeout(() => {
-        document.addEventListener("click", clickHandler);
-      }, 0);
+    if (isOpen) {
+      syncOpenState();
+      positionPopoverMenu();
+      bindReposition();
+      bindConfigChanged();
+      return;
     }
-  };
 
-  const closeMenu = () => {
-    menu.setAttribute("aria-hidden", "true");
-    trigger?.setAttribute("aria-expanded", "false");
+    syncClosedState();
     unbindReposition();
     unbindConfigChanged();
     clearFloatingMenuPosition();
-    setOverlayClippingOverride(false);
+  });
 
-    // Remove click-outside handler when closing
-    if (clickHandler) {
-      document.removeEventListener("click", clickHandler);
-      clickHandler = null;
-    }
+  const openMenu = () => {
+    if (isPopoverOpen()) return;
+    elem.dataset.dropdownDirection = resolveDirection();
+    elem.dataset.dropdownAlign = resolveAlign();
+    menu.showPopover();
+    requestAnimationFrame(() => positionPopoverMenu());
+  };
+
+  const closeMenu = () => {
+    if (!isPopoverOpen()) return;
+    menu.hidePopover();
   };
 
   const toggleMenu = () => {
-    if (menu.getAttribute("aria-hidden") === "false") {
+    if (isPopoverOpen()) {
       closeMenu();
     } else {
       openMenu();
     }
   };
 
+  syncClosedState();
+
+  menu.addEventListener("click", (event) => {
+    const target =
+      event.target instanceof Element ? event.target : event.target?.parentElement;
+    if (!target) return;
+    if (!target.closest("[data-dropdown-close]")) return;
+    closeMenu();
+  });
+
   trigger?.addEventListener("click", (event) => {
     event.preventDefault();
     event.stopPropagation();
@@ -472,19 +390,6 @@ function enhanceDropdown(elem) {
       trigger?.focus();
     }
   });
-
-  elem.addEventListener("focusout", (event) => {
-    // Only close if focus is explicitly moving to an element outside the dropdown
-    // Don't close if relatedTarget is null (which happens when clicking non-focusable elements inside)
-    // Use composedPath() to handle Shadow DOM properly
-    if (event.relatedTarget) {
-      const path = event.composedPath ? event.composedPath() : [event.relatedTarget];
-      const focusedInside = path.some((node) => node === elem);
-      if (!focusedInside) {
-        closeMenu();
-      }
-    }
-  });
 }
 
 function enhanceToggle(elem) {

package/src/js/pds-core/pds-generator.js

@@ -3582,12 +3582,11 @@ dialog {
 
 /*
  * Overlay safety valve:
- * Some controls (e.g. pds-daterange panel, data-dropdown menus) need to escape
+ * Some controls (e.g. pds-daterange panel) need to escape
  * the dialog bounds. Scope overflow visibility to custom dialogs that contain
  * those controls instead of enabling it for all dialogs.
  */
-dialog.dialog-custom:has(pds-daterange),
-dialog.dialog-custom:has([data-dropdown]) {
+dialog.dialog-custom:has(pds-daterange) {
   overflow: visible;
 }
 
@@ -3657,13 +3656,6 @@ dialog {
     overflow-x: visible;
   }
 
-  /* Allow overlay menus (e.g. data-dropdown) to escape dialog-body clipping while open */
-  article:has([data-dropdown] > :last-child[aria-hidden="false"]),
-  form > article:has([data-dropdown] > :last-child[aria-hidden="false"]),
-  .dialog-body:has([data-dropdown] > :last-child[aria-hidden="false"]) {
-    overflow: visible;
-  }
-
   article:has(pds-daterange),
   form > article:has(pds-daterange),
   .dialog-body:has(pds-daterange) {
@@ -3751,7 +3743,8 @@ dialog.dialog-full { width: calc(100vw - var(--spacing-8)); max-width: calc(100v
   dialog, dialog::backdrop { transition-duration: 0.01s !important; }
 }
 
-html:has(dialog[open]:modal) {
+html:has(dialog[open]:modal),
+html:has(pds-drawer[open]) {
  overflow: hidden;
  scrollbar-gutter: stable;
 }
@@ -4096,7 +4089,13 @@ nav[data-dropdown] {
     transition-behavior: allow-discrete;
   }
 
-  & > :last-child[aria-hidden="false"] {
+  & > :last-child[popover] {
+    inset: auto;
+    margin: 0;
+  }
+
+  & > :last-child[aria-hidden="false"],
+  & > :last-child:popover-open {
     display: inline-block;
     opacity: 1;
     visibility: visible;
@@ -4198,7 +4197,8 @@ nav[data-dropdown] {
 }
 
 @starting-style {
-  nav[data-dropdown] > :last-child[aria-hidden="false"] {
+  nav[data-dropdown] > :last-child[aria-hidden="false"],
+  nav[data-dropdown] > :last-child:popover-open {
     opacity: 0;
   }
 }

package/src/js/pds-core/pds-live.js

@@ -319,8 +319,12 @@ async function ensureLiveEditToggleButton() {
     };
 
     menu.appendChild(createItem("toggle", msg("Toggle live editing"), "pencil"));
-    menu.appendChild(createItem("open-settings", msg("Open Settings"), "gear"));
-    menu.appendChild(createSeparator());
+
+    const settingsItem = createItem("open-settings", msg("Open Settings"), "gear");
+    settingsItem.setAttribute("data-dropdown-close", "");
+
+    menu.appendChild(settingsItem);
+    
     menu.appendChild(createItem("reset-config", msg("Reset Config"), "arrow-counter-clockwise"));
 
     await ensureSharedQuickModeToggleMenuItem(menu);

package/src/js/pds-core/pds-ontology.js

@@ -452,8 +452,14 @@ export const ontology = {
     {
       id: "dropdown",
       selector: "nav[data-dropdown]",
-      description: "Dropdown menu from nav element",
-      tags: ["menu", "interactive", "navigation"]
+      description: "Dropdown menu from nav element. Use data-dropdown-close on clickable descendants to dismiss on selection.",
+      tags: ["menu", "interactive", "navigation", "dismiss", "close"]
+    },
+    {
+      id: "dropdown-close",
+      selector: "[data-dropdown-close]",
+      description: "Declarative close marker for nav[data-dropdown] panels; clicking marked targets closes the open dropdown.",
+      tags: ["dropdown", "menu", "dismiss", "close", "attribute"]
     },
     {
       id: "toggle",