@aurodesignsystem-dev/auro-drawer 0.0.0-pr176.0 → 0.0.0-pr180.0

package/demo/api.md

@@ -20,11 +20,11 @@ The `auro-drawer` element provides users a way to implement an expandable drawer
 
 ### Methods
 
-| Name     | Parameters                                                           | Return | Description                                                                                                                                                                                                                                                                                                                                                             |
-| -------- | -------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| hide     | `eventType` (any)                                                    |        | Closes the native dialog.                                                                                                                                                                                                                                                                                                                                               |
-| register | `name` (string) - The name of the element that you want to register. |        | This will register this element with the browser.                                                                                                                                                                                                                                                                                                                       |
-| show     | None                                                                 |        | Opens the native dialog inside the bib.<br><br>- `nested`: `setAttribute("open", "")` to anchor within the parent container.<br>- `!modal && !nested`: `showPopover()` to keep positional CSS intact<br>  and allow free keyboard flow to background content (WCAG 2.1.2).<br>- `modal && !nested`: `showModal()` for native focus containment and top-layer rendering. |
+| Name     | Parameters                                                           | Return | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| -------- | -------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| hide     | `eventType` (any)                                                    |        | Closes the native dialog.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| register | `name` (string) - The name of the element that you want to register. |        | This will register this element with the browser.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| show     | None                                                                 |        | Opens the native dialog inside the bib.<br><br>- `nested`: `setAttribute("open", "")` to anchor within the parent container.<br>- `!modal && !nested`: `showPopover()` to keep positional CSS intact<br>  without taking on `showModal()`'s native modal semantics — `dialog.open`<br>  is not set and the background is never made inert. Browsers without the<br>  Popover API fall back to `dialog.show()`, which does set `dialog.open`<br>  but is likewise non-modal. Focus is still contained on every path:<br>  auro-drawer-content installs a `FocusTrap` regardless of how the dialog<br>  was opened, not just on the `showModal()` one.<br>- `modal && !nested`: `showModal()` for native focus containment and top-layer rendering. |
 
 ### Events
 

package/demo/api.min.js

@@ -2045,6 +2045,48 @@ const computePosition = (reference, floating, options) => {
   });
 };
 
+/**
+ * Generates a v4 UUID with a three-tier fallback for insecure contexts.
+ *
+ * Tier 1 (secure contexts): crypto.randomUUID() — native, fully random.
+ * Tier 2 (insecure contexts): crypto.getRandomValues() — available on all
+ *   modern browsers regardless of secure-context status.
+ * Tier 3 (last resort, no crypto API): new Date().getTime() — lower entropy,
+ *   but sufficient for element IDs where collision risk is negligible.
+ *
+ * See: https://w3c.github.io/webcrypto/#dom-crypto-randomuuid (secure-context restriction)
+ */
+function generateUUID() {
+  let uuid;
+
+  if (
+    typeof crypto !== "undefined" &&
+    typeof crypto.randomUUID === "function"
+  ) {
+    uuid = crypto.randomUUID();
+  } else if (
+    typeof crypto !== "undefined" &&
+    typeof crypto.getRandomValues === "function"
+  ) {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes).map((b) => b.toString(16).padStart(2, "0"));
+    uuid = `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10).join("")}`;
+  } else {
+    let d = new Date().getTime();
+    uuid = "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+      const r = (d % 16) | 0;
+      d = (d - r) / 16 || new Date().getTime();
+      return (c === "x" ? r : (r & 0x3) | 0x8).toString(16);
+    });
+  }
+
+  // CSS selectors require IDs starting with a letter; replace a leading digit with 'a'.
+  return /^[0-9]/.test(uuid) ? `a${uuid.slice(1)}` : uuid;
+}
+
 /* eslint-disable line-comment-position, no-inline-comments */
 
 
@@ -2332,30 +2374,61 @@ class AuroFloatingUI {
 
   /**
    * @private
-   * Controls whether to lock the scrolling for the document's body.
-   * @param {Boolean} lock - If true, locks the body's scrolling functionlity; otherwise, unlock.
+   * Mirrors `aria-modal` onto the `<dialog>` inside the bib, tracking the page
+   * scroll lock: an overlay that holds the page hides it from assistive tech.
+   *
+   * The removal is called only from inside lockScroll()'s ownership guard: run
+   * outside it, it fired on every autoUpdate tick of every NON-owning instance,
+   * and a repositioning dropdown stripped `aria-modal` off an open modal dialog
+   * it had nothing to do with. The write is unguarded by design — see the call
+   * site — but is skipped when the attribute already reads correctly, so the
+   * repeat costs no mutation record.
+   * @param {Boolean} modal - True to mark the dialog modal; false to unmark it.
    */
-  lockScroll(lock = true) {
+  mirrorAriaModal(modal) {
     const element = this.element;
+    const dialog = element?.bib
+      ? (element.bib?.shadowRoot || element.bib || element).querySelector(
+          "dialog",
+        )
+      : undefined;
 
-    if (!element?.bib) {
+    if (!dialog) {
       return;
     }
 
-    const dialog = (
-      element.bib?.shadowRoot ||
-      element.bib ||
-      element
-    ).querySelector("dialog");
-    if (dialog) {
-      if (lock) {
+    if (modal) {
+      if (dialog.getAttribute("aria-modal") !== "true") {
         dialog.setAttribute("aria-modal", "true");
-      } else {
-        dialog.removeAttribute("aria-modal");
       }
+    } else {
+      dialog.removeAttribute("aria-modal");
+    }
+  }
+
+  /**
+   * @private
+   * Controls whether to lock the scrolling for the document's body.
+   * @param {Boolean} lock - If true, locks the body's scrolling functionlity; otherwise, unlock.
+   */
+  lockScroll(lock = true) {
+    const element = this.element;
+
+    // Locking needs a bib to lock around; unlocking must not, or a bib that has
+    // already been detached would leave the page frozen with no way back.
+    if (lock && !element?.bib) {
+      return;
     }
 
     if (lock) {
+      // Re-asserted on every lock call rather than only on the unlocked ->
+      // locked transition. If the bib's inner <dialog> is replaced while this
+      // instance still holds the lock, the replacement would otherwise go
+      // unmarked until a full unlock/lock cycle. Safe to repeat: it targets
+      // this instance's own element, so it cannot reach another overlay's
+      // dialog, and mirrorAriaModal() skips the write when already correct.
+      this.mirrorAriaModal(true);
+
       if (!this._scrollLocked) {
         this._scrollLocked = true;
         this._savedScrollY = window.scrollY;
@@ -2413,6 +2486,8 @@ class AuroFloatingUI {
       }
     } else {
       if (this._scrollLocked) {
+        this.mirrorAriaModal(false);
+
         if (this._viewportHandler && window.visualViewport) {
           window.visualViewport.removeEventListener(
             "resize",
@@ -2525,15 +2600,47 @@ class AuroFloatingUI {
       } else if (this.configureTrial < MAX_CONFIGURATION_COUNT) {
         this.configureTrial += 1;
 
-        setTimeout(() => {
+        // The id is retained so disconnect() can cancel it. A retry that fires
+        // after teardown re-enters this method with isPopoverVisible still true
+        // — nothing clears it on the teardown path — and takes the page scroll
+        // lock back, with no owner left to release it.
+        //
+        // This is not the rare timing race it reads as: the lookup above wants
+        // a `.container` inside the BIB's own shadow root, which only a bib
+        // that is itself a custom element has. A consumer whose bib is a plain
+        // element (auro-dialog's `#bib` is a div, with its `.container` a
+        // sibling in the host's shadow root) can never satisfy it, so it
+        // retries the full MAX_CONFIGURATION_COUNT every time. Correcting the
+        // lookup would change bib sizing for those consumers and is tracked
+        // separately; cancelling the timer is what keeps it from freezing the
+        // page.
+        this._configureRetryId = setTimeout(() => {
+          this._configureRetryId = undefined;
           this.configureBibStrategy(value);
         }, 0);
       }
 
       if (element.isPopoverVisible) {
-        this.lockScroll(value === "fullscreen");
+        // Positioning strategy is not scroll ownership. Both "fullscreen" and
+        // "dialog" lay the bib over the page and trap focus inside it, so both
+        // must freeze the page behind them (AB#1647843). Gating this on
+        // "fullscreen" alone left dismissible desktop dialogs and drawers
+        // scrollable, and actively released the lock on every reposition
+        // (AB#1625424, AB#1625435). The nested "cover" strategy takes the else
+        // branch and stays scrollable by design — it sits inside its parent
+        // rather than over the page.
+        this.lockScroll(true);
       }
     } else {
+      // The mirror of the lock above: a strategy that does not own the page must
+      // hand the lock back, not merely decline to take it. autoUpdate re-runs
+      // this method on every resize tick, and getPositioningStrategy() flips
+      // "fullscreen" -> "floating" across the breakpoint for dropdown behavior —
+      // so an overlay that locked while narrow can land here while still open.
+      // Without this, the page stays frozen behind a small floating bib until
+      // hideBib() happens to run.
+      this.lockScroll(false);
+
       element.bib.style.position = "";
       element.bib.removeAttribute("isfullscreen");
       element.isBibFullscreen = false;
@@ -2643,6 +2750,46 @@ class AuroFloatingUI {
     this.hideBib("focusloss");
   }
 
+  /**
+   * @private
+   * Installs the handlers that dismiss an open overlay.
+   *
+   * Shared by showBib(), which opens the overlay, and configure(), which has to
+   * put these back after a rewire tore them down under an overlay that is still
+   * open. A non-modal overlay dismisses on outside click, focus loss and
+   * Escape; a modal one instead swallows Escape so the native dialog's
+   * CloseWatcher never sees it (AB#1613688).
+   */
+  setupDismissHandlers() {
+    const element = this.element;
+    if (!element) {
+      return;
+    }
+
+    if (!element.modal) {
+      this.setupHideHandlers();
+      return;
+    }
+
+    if (this.keyDownHandler) {
+      document.removeEventListener("keydown", this.keyDownHandler);
+    }
+    this.keyDownHandler = (evt) => {
+      if (evt.key === "Escape" && element.isPopoverVisible) {
+        // Intercept at keydown so CloseWatcher never sees the keystroke.
+        // Canceling `cancel` alone is insufficient — a second Esc with no
+        // intervening user activation triggers the anti-trap and fires `close`
+        // directly, bypassing any `cancel` preventDefault (AB#1613688).
+        // stopImmediatePropagation is intentional: it prevents other document
+        // keydown handlers (e.g. consumer code, auro-dialog) from also acting
+        // on Escape while the modal owns the key.
+        evt.preventDefault();
+        evt.stopImmediatePropagation();
+      }
+    };
+    document.addEventListener("keydown", this.keyDownHandler);
+  }
+
   setupHideHandlers() {
     const element = this.element;
     if (!element) {
@@ -2815,27 +2962,7 @@ class AuroFloatingUI {
 
       // prevent double showing: isPopovervisible gets first and showBib gets called later
       if (!this.showing) {
-        if (!element.modal) {
-          this.setupHideHandlers();
-        } else {
-          if (this.keyDownHandler) {
-            document.removeEventListener("keydown", this.keyDownHandler);
-          }
-          this.keyDownHandler = (evt) => {
-            if (evt.key === "Escape" && element.isPopoverVisible) {
-              // Intercept at keydown so CloseWatcher never sees the keystroke.
-              // Canceling `cancel` alone is insufficient — a second Esc with no
-              // intervening user activation triggers the anti-trap and fires `close`
-              // directly, bypassing any `cancel` preventDefault (AB#1613688).
-              // stopImmediatePropagation is intentional: it prevents other document
-              // keydown handlers (e.g. consumer code, auro-dialog) from also acting
-              // on Escape while the modal owns the key.
-              evt.preventDefault();
-              evt.stopImmediatePropagation();
-            }
-          };
-          document.addEventListener("keydown", this.keyDownHandler);
-        }
+        this.setupDismissHandlers();
         this.showing = true;
         element.isPopoverVisible = true;
         this.position();
@@ -3063,7 +3190,7 @@ class AuroFloatingUI {
 
     this.id = element.getAttribute("id");
     if (!this.id) {
-      this.id = window.crypto.randomUUID();
+      this.id = generateUUID();
       element.setAttribute("id", this.id);
     }
 
@@ -3075,7 +3202,35 @@ class AuroFloatingUI {
     this.enableKeyboardHandling = enableKeyboardHandling;
 
     this.eventPrefix = eventPrefix;
-    if (this.element !== elem) {
+
+    // A retained scroll lock's saved body styles were captured for whichever
+    // element held it, so only a same-element rewire may keep it. An actual
+    // element swap has to take the full teardown, or this instance is left
+    // holding a lock that no longer describes the page it points at — with no
+    // owner able to release it (AB#1647843).
+    const rewiringSameElement = this.element === elem;
+
+    if (!rewiringSameElement) {
+      // Tear down against the outgoing element, before this.element is
+      // repointed. Everything disconnect() releases is element-scoped:
+      // aria-modal on that element's inner dialog, the bib transform saved for
+      // it, its autoUpdate loop and its trigger listeners. Repointing first
+      // aimed all of it at the incoming element — the outgoing dialog kept
+      // aria-modal="true" for good, its bib stayed transformed, and the
+      // incoming bib had the outgoing element's saved transform written onto
+      // it. The trigger gate below read the incoming element's trigger, which
+      // is not assigned until later in this method, so on a swap teardown was
+      // usually skipped outright and the page stayed locked with no owner.
+      if (this.element?.trigger) {
+        this.disconnect({ teardown: true });
+      }
+
+      // disconnect() does not clear this.showing, and the rewire block at the
+      // end of this method only runs for a same-element rewire. Left true, the
+      // incoming element's first showBib() is silently dropped by its
+      // `!this.showing` guard and the overlay never opens.
+      this.showing = false;
+
       this.element = elem;
     }
 
@@ -3088,8 +3243,10 @@ class AuroFloatingUI {
       this.behavior = element.behavior;
     }
 
-    if (element.trigger) {
-      this.disconnect();
+    if (rewiringSameElement && element.trigger) {
+      // Rewiring, not tearing down — an overlay that is open right now keeps
+      // its page scroll lock across a trigger change.
+      this.disconnect({ teardown: false });
     }
     element.trigger =
       element.triggerElement ||
@@ -3118,11 +3275,61 @@ class AuroFloatingUI {
       element.trigger.addEventListener("focus", this.handleEvent);
       element.trigger.addEventListener("blur", this.handleEvent);
     }
+
+    // disconnect() above stripped the dismissal handlers and killed the
+    // autoUpdate loop; the trigger listeners re-registered here replace
+    // neither. An overlay that is open right now would otherwise be left on
+    // screen with outside-click, focus-loss and Escape all dead and its
+    // position frozen — and, since the lock is deliberately retained, holding
+    // the page with only its original trigger able to give it back.
+    if (rewiringSameElement && this.showing) {
+      this.setupDismissHandlers();
+
+      if (element.bib && (element.trigger || element.parentNode)) {
+        element.cleanup = autoUpdate(
+          element.trigger || element.parentNode,
+          element.bib,
+          () => {
+            this.position();
+          },
+        );
+      }
+    }
   }
 
-  disconnect() {
+  /**
+   * Tears the floater's connections down.
+   *
+   * Two callers with different intent share this: a real teardown, which must
+   * release the page scroll lock, and configure(), which re-runs it purely to
+   * rewire a changed trigger and must leave an open overlay's lock alone.
+   * @param {Object} [options] - Teardown options.
+   * @param {Boolean} [options.teardown] - False when only rewiring; keeps the
+   *   page scroll lock held for an overlay that is still open.
+   * @returns {void}
+   */
+  disconnect({ teardown = true } = {}) {
     this.cleanupHideHandlers();
 
+    // Cancel any pending configureBibStrategy() retry. It would otherwise fire
+    // a macrotask after the unlock below, re-lock the page, and leave it frozen
+    // with the floater already gone. Cancelled on a rewire too: configure()
+    // re-runs position() itself, so a stale retry has nothing to contribute.
+    if (this._configureRetryId !== undefined) {
+      clearTimeout(this._configureRetryId);
+      this._configureRetryId = undefined;
+    }
+
+    // Tearing down while the bib is still open would otherwise strand
+    // body{position:fixed} and leave the page permanently unscrollable —
+    // hideBib() is the only other unlock, and it never runs in this path.
+    // Skipped when merely rewiring: configure() routes through here on every
+    // triggerElement change, and releasing the lock there would unlock the page
+    // behind an overlay that is still open (AB#1625424, AB#1625435).
+    if (teardown) {
+      this.lockScroll(false);
+    }
+
     const element = this.element;
     if (!element) {
       return;
@@ -3366,7 +3573,12 @@ class AuroFloater extends i$1 {
    *
    * - `nested`: `setAttribute("open", "")` to anchor within the parent container.
    * - `!modal && !nested`: `showPopover()` to keep positional CSS intact
-   *   and allow free keyboard flow to background content (WCAG 2.1.2).
+   *   without taking on `showModal()`'s native modal semantics — `dialog.open`
+   *   is not set and the background is never made inert. Browsers without the
+   *   Popover API fall back to `dialog.show()`, which does set `dialog.open`
+   *   but is likewise non-modal. Focus is still contained on every path:
+   *   auro-drawer-content installs a `FocusTrap` regardless of how the dialog
+   *   was opened, not just on the `showModal()` one.
    * - `modal && !nested`: `showModal()` for native focus containment and top-layer rendering.
    */
   async show() {
@@ -3426,15 +3638,17 @@ class AuroFloater extends i$1 {
     // the deferred close fires (e.g. when the element is removed from the DOM).
     const dialog = this.bib?.dialog;
     if (dialog?.open) {
-      // Modal and nested drawers: opened via showModal() or setAttribute('open').
+      // Modal and nested drawers (showModal() / setAttribute('open')), and
+      // non-modal drawers on browsers without the Popover API (dialog.show()).
       this._closeTimeout = setTimeout(() => {
         if (dialog.open) {
           dialog.close();
         }
       }, 300);
     } else if (typeof dialog?.hidePopover === "function" && dialog.matches?.(':popover-open')) {
-      // Non-modal drawers: opened via showPopover() — dialog.open is never set,
-      // so the popover stays in the top layer unless hidePopover() is called.
+      // Non-modal drawers opened via showPopover() — that path never sets
+      // dialog.open, so the popover stays in the top layer unless hidePopover()
+      // is called.
       // Guard on hidePopover support: matches(':popover-open') throws a SyntaxError
       // on browsers that don't implement the Popover API.
       this._closeTimeout = setTimeout(() => {
@@ -4395,8 +4609,16 @@ class AuroDrawer extends AuroFloater {
         this.bib.getAttribute("id"),
       );
     }
-    // role="dialog" and aria-modal are provided natively by the <dialog> element;
-    // do not set them manually here.
+    // role="dialog" is provided natively by the <dialog> element — do not set it here.
+    //
+    // aria-modal is NOT, and the distinction matters: native modal semantics come
+    // from how the dialog is opened, not from the element. Only `modal && !nested`
+    // uses showModal(); `!modal && !nested` uses showPopover() (or dialog.show() on
+    // browsers without the Popover API) and `nested` uses setAttribute("open"),
+    // none of which is exposed as modal. auro-library's lockScroll() therefore sets aria-modal on the inner
+    // <dialog> for any presentation that takes the page scroll lock, which is what
+    // makes the dismissible drawer report its modality correctly. See auro-floater.js
+    // show() for the three open paths.
   }
 
   /**