@aurodesignsystem/auro-library 5.12.2 → 5.13.0

package/scripts/runtime/floatingUI.mjs

@@ -62,6 +62,36 @@ export default class AuroFloatingUI {
     }
   }
 
+  static openingQueue = [];
+
+  /**
+   * Returns the currently active floating UI instance that should be considered "on top".
+   * Prefers any globally tracked expanded dropdown or floater, falling back to the last entry in the local opening queue.
+   *
+   * This getter first checks the global document references for a visible floating UI and returns it if found.
+   * If the global reference is stale or not visible, it clears those references and instead returns the most recently opened instance from `openingQueue`, or `null` if none exist.
+   *
+   * Side effect: clears stale global refs so callers don't need a separate cleanup step.
+   */
+  static get topOpeningFloatingUI() {
+    const existedVisibleFloatingUI =
+      document.expandedAuroFormkitDropdown || document.expandedAuroFloater;
+    if (
+      existedVisibleFloatingUI &&
+      existedVisibleFloatingUI.element.isPopoverVisible
+    ) {
+      return existedVisibleFloatingUI;
+    }
+
+    // clear existedVisibleFloatingUI in case it's not flushed well when it hidden by other reasons (e.g. noToggle + click)
+    document.expandedAuroFormkitDropdown = null;
+    document.expandedAuroFloater = null;
+
+    return AuroFloatingUI.openingQueue.length > 0
+      ? AuroFloatingUI.openingQueue[AuroFloatingUI.openingQueue.length - 1]
+      : null;
+  }
+
   constructor(element, behavior) {
     this.element = element;
     this.behavior = behavior;
@@ -161,12 +191,16 @@ export default class AuroFloatingUI {
             `(max-width: ${breakpoint})`,
           ).matches;
 
-          element.expanded = smallerThanBreakpoint;
-        }
-        if (element.nested) {
-          return "cover";
+          this.element.expanded = smallerThanBreakpoint;
+
+          if (this.element.nested) {
+            return "cover";
+          }
+          return smallerThanBreakpoint || this.element.modal
+            ? "fullscreen"
+            : "dialog";
         }
-        return "fullscreen";
+        return "dialog";
       case "dropdown":
       case undefined:
       case null:
@@ -265,17 +299,111 @@ export default class AuroFloatingUI {
   lockScroll(lock = true) {
     const element = this.element;
 
-    if (lock) {
-      if (!element?.bib) {
-        return;
+    if (!element?.bib) {
+      return;
+    }
+
+    const dialog = (
+      element.bib?.shadowRoot ||
+      element.bib ||
+      element
+    ).querySelector("dialog");
+    if (dialog) {
+      if (lock) {
+        dialog.setAttribute("aria-modal", "true");
+      } else {
+        dialog.removeAttribute("aria-modal");
       }
+    }
 
-      document.body.style.overflow = "hidden"; // hide body's scrollbar
+    if (lock) {
+      if (!this._scrollLocked) {
+        this._scrollLocked = true;
+        this._savedScrollY = window.scrollY;
+        this._savedScrollStyles = {
+          rootScrollbarGutter: document.documentElement.style.scrollbarGutter,
+          rootOverflow: document.documentElement.style.overflow,
+          bodyOverflow: document.body.style.overflow,
+          bodyPosition: document.body.style.position,
+          bodyTop: document.body.style.top,
+          bodyWidth: document.body.style.width,
+          bibTransform: element?.bib?.style.transform,
+        };
+        document.documentElement.style.scrollbarGutter = "stable";
+        document.documentElement.style.overflow = "hidden";
+        document.body.style.overflow = "hidden";
+
+        // position:fixed is the only way to block VoiceOver three-finger swipe,
+        // which bypasses both overflow:hidden and touchmove preventDefault.
+        document.body.style.position = "fixed";
+        document.body.style.top = `-${this._savedScrollY}px`;
+        document.body.style.width = "100%";
+
+        // Move `bib` by the amount the viewport is shifted to stay aligned in fullscreen.
+        if (element?.bib && window?.visualViewport?.offsetTop) {
+          element.bib.style.transform = `translateY(${window?.visualViewport?.offsetTop}px)`;
+        }
 
-      // Move `bib` by the amount the viewport is shifted to stay aligned in fullscreen.
-      element.bib.style.transform = `translateY(${window?.visualViewport?.offsetTop}px)`;
+        this.lockTouchScroll(true);
+      }
     } else {
-      document.body.style.overflow = "";
+      if (this._scrollLocked) {
+        document.documentElement.style.scrollbarGutter =
+          this._savedScrollStyles?.rootScrollbarGutter ?? "";
+        document.documentElement.style.overflow =
+          this._savedScrollStyles?.rootOverflow ?? "";
+        document.body.style.overflow =
+          this._savedScrollStyles?.bodyOverflow ?? "";
+        document.body.style.position =
+          this._savedScrollStyles?.bodyPosition ?? "";
+        document.body.style.top = this._savedScrollStyles?.bodyTop ?? "";
+        document.body.style.width = this._savedScrollStyles?.bodyWidth ?? "";
+        if (element?.bib) {
+          element.bib.style.transform =
+            this._savedScrollStyles?.bibTransform ?? "";
+        }
+        window.scrollTo(0, this._savedScrollY || 0);
+        this._savedScrollY = undefined;
+        this._savedScrollStyles = undefined;
+        this._scrollLocked = false;
+
+        this.lockTouchScroll(false);
+      }
+    }
+  }
+
+  /**
+   * Locks page-level touch scroll while bib is open.
+   * Walks composedPath() so scrollable children inside the dialog still scroll.
+   * @private
+   */
+  lockTouchScroll(lock = true) {
+    if (lock) {
+      if (this._boundTouchMoveHandler) {
+        return;
+      }
+      this._boundTouchMoveHandler = (e) => {
+        const path = e.composedPath();
+        const insideScrollable = path.some(
+          (el) =>
+            el !== document &&
+            el !== document.documentElement &&
+            el !== document.body &&
+            (el.scrollHeight > el.clientHeight ||
+              el.scrollWidth > el.clientWidth),
+        );
+        if (!insideScrollable) {
+          e.preventDefault();
+        }
+      };
+      document.addEventListener("touchmove", this._boundTouchMoveHandler, {
+        passive: false,
+      });
+    } else if (this._boundTouchMoveHandler) {
+      document.removeEventListener("touchmove", this._boundTouchMoveHandler, {
+        passive: false,
+      });
+      this._boundTouchMoveHandler = undefined;
     }
   }
 
@@ -294,7 +422,7 @@ export default class AuroFloatingUI {
       return;
     }
 
-    if (value === "fullscreen") {
+    if (value === "fullscreen" || value === "dialog") {
       element.isBibFullscreen = true;
       // reset the prev position
       element.bib.setAttribute("isfullscreen", "");
@@ -322,7 +450,7 @@ export default class AuroFloatingUI {
       }
 
       if (element.isPopoverVisible) {
-        this.lockScroll(true);
+        this.lockScroll(value === "fullscreen");
       }
     } else {
       element.bib.style.position = "";
@@ -595,6 +723,12 @@ export default class AuroFloatingUI {
           this.position();
         },
       );
+
+      const idx = AuroFloatingUI.openingQueue.indexOf(this);
+      if (idx > -1) {
+        AuroFloatingUI.openingQueue.splice(idx, 1);
+      }
+      AuroFloatingUI.openingQueue.push(this);
     }
   }
 
@@ -635,6 +769,10 @@ export default class AuroFloatingUI {
     // Clearing it when hideBib is blocked (e.g. noToggle + click) corrupts
     // the singleton state so other dropdowns can't detect this one is still open.
     document.expandedAuroFloater = null;
+    const idx = AuroFloatingUI.openingQueue.indexOf(this);
+    if (idx > -1) {
+      AuroFloatingUI.openingQueue.splice(idx, 1);
+    }
   }
 
   /**

package/scripts/runtime/floatingUI.test.js

@@ -129,4 +129,271 @@ describe("AuroFloatingUI", () => {
 
     expect(floatingUI.getPositioningStrategy()).to.equal("floating");
   });
+
+  it("restores pre-existing inline scroll styles after lock/unlock", () => {
+    document.documentElement.style.scrollbarGutter = "auto";
+    document.documentElement.style.overflow = "clip";
+    document.body.style.overflow = "scroll";
+    document.body.style.position = "sticky";
+    document.body.style.top = "12px";
+    document.body.style.width = "75%";
+    const scrollToStub = sinon.stub(window, "scrollTo");
+
+    floatingUI.lockScroll(true);
+
+    expect(document.documentElement.style.scrollbarGutter).to.equal("stable");
+    expect(document.documentElement.style.overflow).to.equal("hidden");
+    expect(document.body.style.overflow).to.equal("hidden");
+    expect(document.body.style.position).to.equal("fixed");
+    expect(document.body.style.width).to.equal("100%");
+
+    floatingUI.lockScroll(false);
+
+    expect(document.documentElement.style.scrollbarGutter).to.equal("auto");
+    expect(document.documentElement.style.overflow).to.equal("clip");
+    expect(document.body.style.overflow).to.equal("scroll");
+    expect(document.body.style.position).to.equal("sticky");
+    expect(document.body.style.top).to.equal("12px");
+    expect(document.body.style.width).to.equal("75%");
+    expect(scrollToStub.calledOnceWithExactly(0, 0)).to.be.true;
+    expect(floatingUI._boundTouchMoveHandler).to.equal(undefined);
+  });
+
+  it("prevents touch scroll when gesture is outside scrollable content", () => {
+    floatingUI.lockTouchScroll(true);
+
+    const preventDefault = sinon.spy();
+    floatingUI._boundTouchMoveHandler({
+      composedPath: () => [document.body],
+      preventDefault,
+    });
+
+    expect(preventDefault.calledOnce).to.be.true;
+  });
+
+  it("allows touch scroll when gesture is inside scrollable content", () => {
+    floatingUI.lockTouchScroll(true);
+
+    const scrollable = document.createElement("div");
+    Object.defineProperty(scrollable, "scrollHeight", {
+      configurable: true,
+      value: 200,
+    });
+    Object.defineProperty(scrollable, "clientHeight", {
+      configurable: true,
+      value: 100,
+    });
+
+    const preventDefault = sinon.spy();
+    floatingUI._boundTouchMoveHandler({
+      composedPath: () => [scrollable],
+      preventDefault,
+    });
+
+    expect(preventDefault.called).to.be.false;
+  });
+  it("lockScroll sets _scrollLocked flag when locking", () => {
+    floatingUI.lockScroll(true);
+    expect(floatingUI._scrollLocked).to.be.true;
+    floatingUI.lockScroll(false);
+    expect(floatingUI._scrollLocked).to.be.false;
+  });
+
+  it("lockScroll saves scroll position when locking", () => {
+    const originalScrollY = window.scrollY;
+    floatingUI.lockScroll(true);
+    expect(floatingUI._savedScrollY).to.equal(originalScrollY);
+  });
+
+  it("lockScroll restores scroll position when unlocking", () => {
+    floatingUI.lockScroll(true);
+    window.scrollTo(0, 500);
+    floatingUI.lockScroll(false);
+    // Note: scrollTo may not work in test environment, but the restoration logic is in place
+    expect(floatingUI._scrollLocked).to.be.false;
+  });
+
+  it("lockTouchScroll creates event handler when locking", () => {
+    expect(floatingUI._boundTouchMoveHandler).to.be.undefined;
+    floatingUI.lockTouchScroll(true);
+    expect(floatingUI._boundTouchMoveHandler).to.be.a("function");
+  });
+
+  it("lockTouchScroll removes event handler when unlocking", () => {
+    floatingUI.lockTouchScroll(true);
+    floatingUI.lockTouchScroll(false);
+    expect(floatingUI._boundTouchMoveHandler).to.be.undefined;
+  });
+
+  it("lockTouchScroll prevents default on non-scrollable elements", () => {
+    floatingUI.lockTouchScroll(true);
+    const nonScrollable = document.createElement("div");
+    const preventDefault = sinon.spy();
+    const touchEvent = {
+      composedPath: () => [nonScrollable],
+      preventDefault,
+    };
+    floatingUI._boundTouchMoveHandler(touchEvent);
+    expect(preventDefault.called).to.be.true;
+  });
+
+  it("lockTouchScroll allows touchmove on scrollable elements", () => {
+    floatingUI.lockTouchScroll(true);
+    const scrollable = document.createElement("div");
+    Object.defineProperty(scrollable, "scrollHeight", {
+      configurable: true,
+      value: 200,
+    });
+    Object.defineProperty(scrollable, "clientHeight", {
+      configurable: true,
+      value: 100,
+    });
+    const preventDefault = sinon.spy();
+    const touchEvent = {
+      composedPath: () => [scrollable],
+      preventDefault,
+    };
+    floatingUI._boundTouchMoveHandler(touchEvent);
+    expect(preventDefault.called).to.be.false;
+  });
+
+  it("configureBibStrategy sets isfullscreen attribute for fullscreen", () => {
+    host.bib = bib;
+    host.isPopoverVisible = false;
+    floatingUI.configureBibStrategy("fullscreen");
+    expect(bib.getAttribute("isfullscreen")).to.equal("");
+    expect(host.isBibFullscreen).to.be.true;
+  });
+
+  it("configureBibStrategy removes isfullscreen attribute for floating", () => {
+    host.bib = bib;
+    bib.setAttribute("isfullscreen", "");
+    host.isBibFullscreen = true;
+    floatingUI.configureBibStrategy("floating");
+    expect(bib.hasAttribute("isfullscreen")).to.be.false;
+    expect(host.isBibFullscreen).to.be.false;
+  });
+
+  it("getPositioningStrategy returns 'dialog' for dialog behavior without breakpoint", () => {
+    floatingUI.behavior = "dialog";
+    host.floaterConfig = {};
+    const strategy = floatingUI.getPositioningStrategy();
+    expect(strategy).to.equal("dialog");
+  });
+
+  it("getPositioningStrategy returns 'floating' for undefined behavior", () => {
+    floatingUI.behavior = undefined;
+    host.floaterConfig = {};
+    const strategy = floatingUI.getPositioningStrategy();
+    expect(strategy).to.equal("floating");
+  });
+
+  it("getPositioningStrategy returns 'floating' when element is missing", () => {
+    floatingUI.element = null;
+    const strategy = floatingUI.getPositioningStrategy();
+    expect(strategy).to.equal("floating");
+  });
+});
+
+describe("AuroFloatingUI.openingQueue and topOpeningFloatingUI", () => {
+  let floatingUI1;
+  let floatingUI2;
+  let floatingUI3;
+  let host1;
+  let host2;
+  let host3;
+  let bib1;
+  let bib2;
+  let bib3;
+
+  beforeEach(() => {
+    AuroFloatingUI.openingQueue = [];
+    document.expandedAuroFormkitDropdown = null;
+    document.expandedAuroFloater = null;
+
+    host1 = document.createElement("div");
+    bib1 = document.createElement("div");
+    host1.bib = bib1;
+    host1.isPopoverVisible = false;
+    document.body.append(host1, bib1);
+    floatingUI1 = new AuroFloatingUI(host1, "dropdown");
+
+    host2 = document.createElement("div");
+    bib2 = document.createElement("div");
+    host2.bib = bib2;
+    host2.isPopoverVisible = false;
+    document.body.append(host2, bib2);
+    floatingUI2 = new AuroFloatingUI(host2, "dropdown");
+
+    host3 = document.createElement("div");
+    bib3 = document.createElement("div");
+    host3.bib = bib3;
+    host3.isPopoverVisible = false;
+    document.body.append(host3, bib3);
+    floatingUI3 = new AuroFloatingUI(host3, "dropdown");
+  });
+
+  afterEach(() => {
+    AuroFloatingUI.openingQueue = [];
+    document.expandedAuroFormkitDropdown = null;
+    document.expandedAuroFloater = null;
+    host1?.remove();
+    host2?.remove();
+    host3?.remove();
+    bib1?.remove();
+    bib2?.remove();
+    bib3?.remove();
+    sinon.restore();
+  });
+
+  it("can add instances to openingQueue", () => {
+    AuroFloatingUI.openingQueue.push(floatingUI1);
+    expect(AuroFloatingUI.openingQueue).to.include(floatingUI1);
+    expect(AuroFloatingUI.openingQueue.length).to.equal(1);
+  });
+
+  it("maintains insertion order in openingQueue", () => {
+    AuroFloatingUI.openingQueue.push(floatingUI1);
+    AuroFloatingUI.openingQueue.push(floatingUI2);
+    expect(AuroFloatingUI.openingQueue[0]).to.equal(floatingUI1);
+    expect(AuroFloatingUI.openingQueue[1]).to.equal(floatingUI2);
+  });
+
+  it("can remove instances from openingQueue", () => {
+    AuroFloatingUI.openingQueue.push(floatingUI1);
+    AuroFloatingUI.openingQueue.push(floatingUI2);
+    const index = AuroFloatingUI.openingQueue.indexOf(floatingUI1);
+    AuroFloatingUI.openingQueue.splice(index, 1);
+    expect(AuroFloatingUI.openingQueue).to.not.include(floatingUI1);
+    expect(AuroFloatingUI.openingQueue).to.include(floatingUI2);
+  });
+
+  it("topOpeningFloatingUI returns global reference when visible", () => {
+    document.expandedAuroFloater = floatingUI1;
+    floatingUI1.element.isPopoverVisible = true;
+    const topUI = AuroFloatingUI.topOpeningFloatingUI;
+    expect(topUI).to.equal(floatingUI1);
+  });
+
+  it("topOpeningFloatingUI returns queue last entry when global ref is stale", () => {
+    document.expandedAuroFloater = floatingUI1;
+    floatingUI1.element.isPopoverVisible = false;
+    AuroFloatingUI.openingQueue.push(floatingUI2);
+    floatingUI2.element.isPopoverVisible = true;
+    const topUI = AuroFloatingUI.topOpeningFloatingUI;
+    expect(topUI).to.equal(floatingUI2);
+  });
+
+  it("topOpeningFloatingUI returns last entry from queue", () => {
+    AuroFloatingUI.openingQueue.push(floatingUI1);
+    AuroFloatingUI.openingQueue.push(floatingUI2);
+    AuroFloatingUI.openingQueue.push(floatingUI3);
+    const topUI = AuroFloatingUI.topOpeningFloatingUI;
+    expect(topUI).to.equal(floatingUI3);
+  });
+
+  it("topOpeningFloatingUI returns null when queue is empty", () => {
+    const topUI = AuroFloatingUI.topOpeningFloatingUI;
+    expect(topUI).to.be.null;
+  });
 });