@aurodesignsystem-dev/auro-formkit 0.0.0-pr1492.4 → 0.0.0-pr1493.0

package/components/dropdown/demo/css-only.md

@@ -0,0 +1,219 @@
+<auro-header level="1">CSS only with native disclosure</auro-header>
+<p>For situations where the <code>&lt;auro-dropdown&gt;</code> web component cannot be used, a native HTML <code>&lt;details&gt;</code>/<code>&lt;summary&gt;</code> element can be styled with the Auro Design System tokens to approximate the visual appearance of <code>auro-dropdown</code>. Unlike <auro-hyperlink href="https://auro.alaskaair.com/components/auro/hyperlink/css-only" target="_blank">auro-hyperlink</auro-hyperlink>, <auro-hyperlink href="https://alaskaairlines.github.io/WebCoreStyleSheets/" target="_blank">Web Core Style Sheets</auro-hyperlink> does not provide a prebuilt <code>.dropdown</code> class, so the styling must be authored manually using Auro design tokens.</p>
+<auro-header level="2">Styling a native disclosure</auro-header>
+<p>The native <code>&lt;details&gt;</code>/<code>&lt;summary&gt;</code> pair can be reset and restyled with the Auro design tokens published by <auro-hyperlink href="https://alaskaairlines.github.io/WebCoreStyleSheets/" target="_blank">@aurodesignsystem/design-tokens</auro-hyperlink>. The pattern below replicates the trigger border, spacing, and panel colors used by <code>auro-dropdown</code>.</p>
+<pre><code>@import "./node_modules/@aurodesignsystem/design-tokens/dist/tokens/CSSCustomProperties.css";
+​
+.dropdown {
+  position: relative;
+  display: inline-block;
+}
+​
+.dropdown &gt; summary {
+  list-style: none;
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  gap: var(--ds-size-100, 0.5rem);
+  padding: var(--ds-size-100, 0.5rem) var(--ds-size-150, 0.75rem);
+  border: 1px solid var(--ds-color-border-ui-default, #6e767f);
+  border-radius: var(--ds-border-radius, 4px);
+  background-color: var(--ds-color-container-primary-default, #ffffff);
+  color: var(--ds-color-text-primary-default, #1d1d1d);
+  font-family: var(--ds-font-family-default, sans-serif);
+}
+​
+.dropdown &gt; summary::-webkit-details-marker {
+  display: none;
+}
+​
+.dropdown &gt; summary::after {
+  content: "";
+  width: var(--ds-size-150, 0.75rem);
+  height: var(--ds-size-150, 0.75rem);
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%231d1d1d' stroke-width='2'%3E%3Cpolyline points='6 9 12 15 18 9'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: center;
+  transition: transform 150ms ease;
+}
+​
+.dropdown[open] &gt; summary::after {
+  transform: rotate(180deg);
+}
+​
+.dropdown &gt; summary:focus-visible {
+  outline: 2px solid var(--ds-color-border-active-default, #01426a);
+  outline-offset: 2px;
+}
+​
+.dropdown-bib {
+  position: absolute;
+  top: calc(100% + var(--ds-size-50, 0.25rem));
+  left: 0;
+  z-index: 1;
+  min-width: 100%;
+  padding: var(--ds-size-100, 0.5rem);
+  border: 1px solid var(--ds-color-border-ui-default, #6e767f);
+  border-radius: var(--ds-border-radius, 4px);
+  background-color: var(--ds-color-container-primary-default, #ffffff);
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+}</code></pre>
+<auro-header level="3">Basic disclosure</auro-header>
+<p>Apply the <code>.dropdown</code> class to a <code>&lt;details&gt;</code> element with a <code>&lt;summary&gt;</code> trigger and a panel container:</p>
+<pre><code>&lt;details class="dropdown"&gt;
+  &lt;summary&gt;More options&lt;/summary&gt;
+  &lt;div class="dropdown-bib"&gt;
+    &lt;p&gt;Panel content goes here.&lt;/p&gt;
+  &lt;/div&gt;
+&lt;/details&gt;</code></pre>
+<auro-header level="3">Disclosure with a list of actions</auro-header>
+<p>The panel can hold any markup. For a menu-like list, author the items as a plain unordered list:</p>
+<pre><code>&lt;details class="dropdown"&gt;
+  &lt;summary&gt;Account&lt;/summary&gt;
+  &lt;div class="dropdown-bib"&gt;
+    &lt;ul&gt;
+      &lt;li&gt;&lt;a href="/profile"&gt;Profile&lt;/a&gt;&lt;/li&gt;
+      &lt;li&gt;&lt;a href="/settings"&gt;Settings&lt;/a&gt;&lt;/li&gt;
+      &lt;li&gt;&lt;a href="/logout"&gt;Log out&lt;/a&gt;&lt;/li&gt;
+    &lt;/ul&gt;
+  &lt;/div&gt;
+&lt;/details&gt;</code></pre>
+<auro-header level="2">What you lose without auro-dropdown</auro-header>
+<p>While the CSS above replicates the <strong>visual styling</strong> of <code>auro-dropdown</code>, the following functionality built into the <code>auro-dropdown</code> web component is <strong>not available</strong> when using plain HTML:</p>
+<auro-header level="3">Floating-UI positioning</auro-header>
+<p><code>auro-dropdown</code> uses Floating UI to position the bib relative to the trigger and supports a <code>placement</code> attribute with twelve values (<code>top</code>, <code>right</code>, <code>bottom</code>, <code>left</code>, and their <code>-start</code>/<code>-end</code> variants). A native <code>&lt;details&gt;</code> panel is absolutely positioned by the author and does not adapt to alternate placements without additional CSS for each case.</p>
+<auro-header level="3">Auto-placement and flip</auro-header>
+<p><code>auro-dropdown</code> exposes <code>autoPlacement</code> and the inverse <code>noFlip</code> option so the bib can automatically pick the side of the trigger with the most available space and flip when it would otherwise be clipped by the viewport. A CSS-only panel stays where it is authored and will overflow the viewport when there is not enough room.</p>
+<auro-header level="3">Shift to stay on-screen</auro-header>
+<p><code>auro-dropdown</code> supports a <code>shift</code> attribute that nudges the bib along its axis so it remains fully visible inside the viewport. Native disclosures have no equivalent — a panel positioned with CSS that runs past the viewport edge is simply clipped or causes horizontal scroll.</p>
+<auro-header level="3">Match-width and offset control</auro-header>
+<p><code>auro-dropdown</code> exposes <code>matchWidth</code> to size the bib to the trigger and a numeric <code>offset</code> for the gap between trigger and bib. With native HTML, both must be implemented manually with CSS and, in the case of dynamic trigger widths, JavaScript measurement.</p>
+<auro-header level="3">Mobile fullscreen behavior</auro-header>
+<p><code>auro-dropdown</code> supports a <code>fullscreenBreakpoint</code> (defaulting to <code>sm</code>) that switches the bib into a fullscreen presentation on small viewports, and a <code>desktopModal</code> option for modal behavior on larger viewports. Native <code>&lt;details&gt;</code> has no responsive presentation — the panel renders the same way on every screen size.</p>
+<auro-header level="3">Hover trigger</auro-header>
+<p><code>auro-dropdown</code> supports a <code>hoverToggle</code> attribute that opens the bib on mouseover and closes it on mouseout. Native <code>&lt;details&gt;</code> only responds to click on the <code>&lt;summary&gt;</code>; hover-to-open requires custom JavaScript.</p>
+<auro-header level="3">Focus management</auro-header>
+<p><code>auro-dropdown</code> provides a <code>focus()</code> method that moves focus to the first focusable element inside the bib when it is open, or to the trigger when it is closed. It also supports <code>focusShow</code> to open the bib on trigger focus. Native <code>&lt;details&gt;</code> leaves focus on the <code>&lt;summary&gt;</code> after toggle and offers no built-in focus-into-panel behavior.</p>
+<auro-header level="3">Click-outside and focus-loss dismissal</auro-header>
+<p><code>auro-dropdown</code> closes the bib when the user clicks outside the component or moves focus out of it, and exposes <code>noHideOnThisFocusLoss</code> to opt out. Native <code>&lt;details&gt;</code> stays open until the <code>&lt;summary&gt;</code> is clicked again — click-outside and focus-out dismissal must be wired up manually.</p>
+<auro-header level="3">Keyboard handling</auro-header>
+<p><code>auro-dropdown</code> includes a keyboard strategy for arrow-key navigation, <code>Escape</code> to close, and <code>Tab</code> behavior coordinated with the bib contents, and lets consumers opt out via <code>disableKeyboardHandling</code>. Native <code>&lt;details&gt;</code> only toggles on <code>Enter</code>/<code>Space</code> on the <code>&lt;summary&gt;</code> and offers no panel-internal keyboard model.</p>
+<auro-header level="3">ARIA wiring</auro-header>
+<p><code>auro-dropdown</code> sets an <code>a11yRole</code> on the trigger, manages <code>aria-expanded</code>, and emits an <code>auroDropdown-idAdded</code> event so consumers can wire <code>aria-controls</code> to the generated bib ID. Native <code>&lt;details&gt;</code> exposes a disclosure role with <code>open</code> state but does not expose a generated panel ID, and any custom role (for example, <code>combobox</code> or <code>menu</code>) must be added and kept in sync by hand.</p>
+<auro-header level="3">Chevron indicator</auro-header>
+<p><code>auro-dropdown</code> supports a <code>chevron</code> attribute that renders a collapsed/expanded indicator with the correct rotation and design-token color. With native HTML you must author the indicator yourself — the example above uses a background-image SVG and a <code>[open]</code> selector to rotate it.</p>
+<auro-header level="3">Error and help-text presentation</auro-header>
+<p><code>auro-dropdown</code> exposes <code>error</code>, <code>errorMessage</code>, and a <code>helpText</code> slot that renders supporting text below the trigger with the correct error styling. Native <code>&lt;details&gt;</code> has no concept of error state or help text — both must be authored and toggled manually.</p>
+<auro-header level="3">Imperative show/hide and toggle events</auro-header>
+<p><code>auro-dropdown</code> exposes <code>show()</code> and <code>hide()</code> methods, a <code>disableEventShow</code> option to lock it to programmatic control, and emits <code>auroDropdown-toggled</code> and <code>auroDropdown-triggerClick</code> events. Native <code>&lt;details&gt;</code> emits a single <code>toggle</code> event and is toggled by user interaction with the <code>&lt;summary&gt;</code>; coordinated open/close logic across components must be written by hand.</p>
+<auro-header level="3">Multi-brand theming</auro-header>
+<p><code>auro-dropdown</code> consumes Auro design tokens through its component logic, so it automatically picks up brand-specific theming when token packages are swapped. A CSS-only disclosure is tied to whichever tokens were imported at author time and will not respond to runtime theme switching the way the web component does.</p>
+<auro-header level="2">Summary</auro-header>
+<table>
+<thead>
+<tr>
+<th>Feature</th>
+<th>Native <code>&lt;details&gt;</code>/<code>&lt;summary&gt;</code> with Auro tokens</th>
+<th><code>auro-dropdown</code></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Design-system-aligned styling</td>
+<td>Manual (author-written CSS)</td>
+<td>Built-in</td>
+</tr>
+<tr>
+<td>Dark background support</td>
+<td>Manual</td>
+<td>Yes (<code>appearance="inverse"</code>)</td>
+</tr>
+<tr>
+<td>Bib placement</td>
+<td>Fixed by author CSS</td>
+<td>12 <code>placement</code> values</td>
+</tr>
+<tr>
+<td>Auto-placement and flip</td>
+<td>Not supported</td>
+<td><code>autoPlacement</code> / <code>noFlip</code></td>
+</tr>
+<tr>
+<td>Shift to stay on-screen</td>
+<td>Not supported</td>
+<td><code>shift</code></td>
+</tr>
+<tr>
+<td>Match trigger width</td>
+<td>Manual CSS/JS</td>
+<td><code>matchWidth</code></td>
+</tr>
+<tr>
+<td>Offset / gap control</td>
+<td>Manual CSS</td>
+<td><code>offset</code></td>
+</tr>
+<tr>
+<td>Mobile fullscreen</td>
+<td>Not supported</td>
+<td><code>fullscreenBreakpoint</code></td>
+</tr>
+<tr>
+<td>Desktop modal</td>
+<td>Not supported</td>
+<td><code>desktopModal</code></td>
+</tr>
+<tr>
+<td>Hover to open</td>
+<td>Manual JS</td>
+<td><code>hoverToggle</code></td>
+</tr>
+<tr>
+<td>Focus into bib on open</td>
+<td>Manual JS</td>
+<td><code>focus()</code> / <code>focusShow</code></td>
+</tr>
+<tr>
+<td>Click-outside / focus-loss dismiss</td>
+<td>Manual JS</td>
+<td>Built-in (with opt-out)</td>
+</tr>
+<tr>
+<td>Keyboard model</td>
+<td><code>Enter</code>/<code>Space</code> on summary only</td>
+<td>Arrow / <code>Escape</code> / <code>Tab</code> strategy</td>
+</tr>
+<tr>
+<td>ARIA wiring</td>
+<td>Native disclosure role only</td>
+<td><code>a11yRole</code>, <code>aria-expanded</code>, generated bib ID</td>
+</tr>
+<tr>
+<td>Chevron indicator</td>
+<td>Manual</td>
+<td><code>chevron</code></td>
+</tr>
+<tr>
+<td>Error / help text</td>
+<td>Manual</td>
+<td><code>error</code>, <code>errorMessage</code>, <code>helpText</code> slot</td>
+</tr>
+<tr>
+<td>Imperative show / hide</td>
+<td>Not supported</td>
+<td><code>show()</code> / <code>hide()</code></td>
+</tr>
+<tr>
+<td>Toggle events</td>
+<td><code>toggle</code></td>
+<td><code>auroDropdown-toggled</code>, <code>auroDropdown-triggerClick</code></td>
+</tr>
+<tr>
+<td>Multi-brand theming</td>
+<td>Static (import-time tokens)</td>
+<td>Full (design tokens + component logic)</td>
+</tr>
+</tbody>
+</table>
+<auro-header level="2">Recommendation</auro-header>
+<p>Use <code>auro-dropdown</code> whenever possible. Fall back to a CSS-styled native <code>&lt;details&gt;</code>/<code>&lt;summary&gt;</code> only in environments where custom elements are not supported or when integrating with third-party systems that require plain HTML — and be prepared to reimplement positioning, focus management, click-outside dismissal, keyboard behavior, and responsive presentation yourself.</p>

package/components/dropdown/demo/customize.md

@@ -13,6 +13,7 @@
 <auro-anchorlink fluid href="#matchWidth" class="level2 body-xs">Match Width</auro-anchorlink>
 <auro-anchorlink fluid href="#customBehavior">Behavior</auro-anchorlink>
 <auro-anchorlink fluid href="#chevron" class="level2 body-xs">Chevron</auro-anchorlink>
+<auro-anchorlink fluid href="#desktopModal" class="level2 body-xs">Desktop Modal</auro-anchorlink>
 <auro-anchorlink fluid href="#disabled" class="level2 body-xs">Disabled</auro-anchorlink>
 <auro-anchorlink fluid href="#error" class="level2 body-xs">Error</auro-anchorlink>
 <auro-anchorlink fluid href="#noToggle" class="level2 body-xs">No Toggle</auro-anchorlink>
@@ -569,6 +570,8 @@
 &lt;/auro-dropdown&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
+<auro-header level="3" id="desktopModal">Desktop Modal</auro-header>
+<p>Use the <code>desktopModal</code> attribute to make the dropdown behave as a modal dialog on desktop viewports. When set, all sibling elements on the page are marked <code>inert</code> and focus is trapped within the bib content. In fullscreen mode, the native <code>&lt;dialog&gt;</code> <code>showModal()</code> API provides equivalent behavior automatically.</p>
 <auro-header level="3" id="disabled">Disabled</auro-header>
 <p>Use the <code>disabled</code> attribute to disable interaction with the dropdown.</p>
 <div class="exampleWrapper">

package/components/dropdown/demo/customize.min.js

@@ -3311,7 +3311,7 @@ function applyKeyboardStrategy(component, strategy, options = {}) {
   });
 }
 
-var styleCss$2 = i$2`:host{position:fixed;z-index:var(--depth-tooltip, 400);display:none;isolation:isolate}:host dialog{width:auto;max-width:none;height:auto;max-height:none;padding:0;border:none;margin:0;outline:none;transform:translateZ(0)}:host dialog::backdrop{background:transparent}:host(:not([isfullscreen])) dialog{position:relative;inset:unset}:host(:not([isfullscreen])) .container.shape-box{border-radius:unset}:host(:not([isfullscreen])) .container[class*=shape-pill],:host(:not([isfullscreen])) .container[class*=shape-snowflake]{border-radius:30px}:host(:not([isfullscreen])) .container[class*=shape-rounded]{border-radius:16px}:host(:not([matchWidth])) .container{min-width:fit-content}:host([isfullscreen]){position:fixed;top:0;left:0}:host([isfullscreen]) .container{width:100dvw;max-width:none;height:100dvh;max-height:none;border-radius:unset;margin-top:0;box-shadow:unset;overscroll-behavior:contain}:host([isfullscreen]) .container::backdrop{background:var(--ds-color-background-primary, #fff)}:host(:popover-open){position:fixed;overflow:visible;padding:0;border:none;margin:0;background:transparent;inset:unset;outline:none}:host([data-show]){display:flex}:host([common]:not([isfullscreen])) .container,:host([rounded]:not([isfullscreen])) .container{border-radius:var(--ds-border-radius, 0.375rem)}:host([common][isfullscreen]) .container,:host([rounded][isfullscreen]) .container{border-radius:unset;box-shadow:unset}.container{display:inline-block;overflow:auto;box-sizing:border-box;border-radius:var(--ds-border-radius, 0.375rem);margin:var(--ds-size-50, 0.25rem) 0}.util_displayHiddenVisually{position:absolute;overflow:hidden;width:1px;height:1px;padding:0;border:0;margin:-1px;clip-path:inset(50%);white-space:nowrap}`;
+var styleCss$2 = i$2`:host{position:fixed;z-index:var(--depth-tooltip, 400);display:none;isolation:isolate}:host dialog{width:auto;max-width:none;height:auto;max-height:none;padding:0;border:none;margin:0;outline:none;transform:translateZ(0)}:host dialog::backdrop{background:transparent}:host(:not([isfullscreen])) dialog{position:relative;inset:unset}:host(:not([isfullscreen])) .container.shape-box{border-radius:unset}:host(:not([isfullscreen])) .container[class*=shape-pill],:host(:not([isfullscreen])) .container[class*=shape-snowflake]{border-radius:30px}:host(:not([isfullscreen])) .container[class*=shape-rounded]{border-radius:16px}:host([desktopmodal]:popover-open)::backdrop{background:transparent}:host(:not([matchWidth])) .container{min-width:fit-content}:host([isfullscreen]){position:fixed;top:0;left:0}:host([isfullscreen]) .container{width:100dvw;max-width:none;height:100dvh;max-height:none;border-radius:unset;margin-top:0;box-shadow:unset;overscroll-behavior:contain}:host([isfullscreen]) .container::backdrop{background:var(--ds-color-background-primary, #fff)}:host(:popover-open){position:fixed;overflow:visible;padding:0;border:none;margin:0;background:transparent;inset:unset;outline:none}:host([data-show]){display:flex}:host([common]:not([isfullscreen])) .container,:host([rounded]:not([isfullscreen])) .container{border-radius:var(--ds-border-radius, 0.375rem)}:host([common][isfullscreen]) .container,:host([rounded][isfullscreen]) .container{border-radius:unset;box-shadow:unset}.container{display:inline-block;overflow:auto;box-sizing:border-box;border-radius:var(--ds-border-radius, 0.375rem);margin:var(--ds-size-50, 0.25rem) 0}.util_displayHiddenVisually{position:absolute;overflow:hidden;width:1px;height:1px;padding:0;border:0;margin:-1px;clip-path:inset(50%);white-space:nowrap}`;
 
 var colorCss$2 = i$2`.container{background-color:var(--ds-auro-dropdownbib-container-color);box-shadow:var(--ds-auro-dropdownbib-boxshadow-color);color:var(--ds-auro-dropdownbib-text-color)}`;
 
@@ -3942,7 +3942,7 @@ class AuroHelpText extends i {
   }
 }
 
-var formkitVersion = '202606031929';
+var formkitVersion = '202606181613';
 
 class AuroElement extends i {
   static get properties() {
@@ -4122,6 +4122,7 @@ class AuroDropdown extends AuroElement {
   _intializeDefaults() {
     this.appearance = 'default';
     this.chevron = false;
+    this.desktopModal = false;
     this.disabled = false;
     this.disableKeyboardHandling = false;
     this.error = false;
@@ -4302,6 +4303,14 @@ class AuroDropdown extends AuroElement {
         reflect: true
       },
 
+      /**
+       * If declared, the dropdown will behave as a modal dialog when in a desktop viewport size.
+       */
+      desktopModal: {
+        type: Boolean,
+        reflect: true
+      },
+
       /**
        * If declared, the dropdown will only show by calling the API .show() public method.
        */
@@ -4589,6 +4598,15 @@ class AuroDropdown extends AuroElement {
 
   disconnectedCallback() {
     super.disconnectedCallback();
+    this._clearPageInert();
+    if (this._bibTabHandler) {
+      this.removeEventListener('keydown', this._bibTabHandler);
+      this._bibTabHandler = undefined;
+    }
+    if (this.focusTrap) {
+      this.focusTrap.disconnect();
+      this.focusTrap = undefined;
+    }
     if (this.floater) {
       this.floater.hideBib('disconnect');
       this.floater.disconnect();
@@ -4616,19 +4634,45 @@ class AuroDropdown extends AuroElement {
       if (this.isPopoverVisible) {
         // Fullscreen: use showModal() for native accessibility (inert outside, focus trap)
         // Desktop: use show() for Floating UI positioning + FocusTrap for focus management
-        const useModal = this.isBibFullscreen;
-        this.bibElement.value.open(useModal);
+        this.bibElement.value.open(this.isBibFullscreen);
+        this.updateFocusTrap();
+
+        // Desktop modal: make siblings inert so content outside is not interactive
+        if (this.desktopModal && !this.isBibFullscreen) {
+          this._setPageInert();
+        }
       } else {
         this.bibElement.value.close();
+        this._clearPageInert();
       }
     }
 
     // When fullscreen strategy changes while open, re-open dialog with correct mode
     // (e.g. resizing from desktop → mobile while dropdown is open)
     if (changedProperties.has('isBibFullscreen') && this.isPopoverVisible && this.bibElement.value) {
-      const useModal = this.isBibFullscreen;
       this.bibElement.value.close();
-      this.bibElement.value.open(useModal);
+      this.bibElement.value.open(this.isBibFullscreen);
+
+      // Re-initialize focus management for the new strategy
+      this.updateFocusTrap();
+
+      // Toggle inert: desktop modal needs it, fullscreen showModal() handles it natively
+      if (this.desktopModal && !this.isBibFullscreen) {
+        this._setPageInert();
+      } else {
+        this._clearPageInert();
+      }
+    }
+
+    // Handle desktopModal toggled while the dropdown is already open.
+    // Re-initialize focus trapping and page inert state to match the new mode.
+    if (changedProperties.has('desktopModal') && this.isPopoverVisible && !this.isBibFullscreen) {
+      this.updateFocusTrap();
+      if (this.desktopModal) {
+        this._setPageInert();
+      } else {
+        this._clearPageInert();
+      }
     }
   }
 
@@ -4638,8 +4682,14 @@ class AuroDropdown extends AuroElement {
    * @param {CustomEvent} event - The custom event that contains the dropdown toggle information.
    */
   handleDropdownToggle(event) {
-    this.updateFocusTrap();
     this.isPopoverVisible = event.detail.expanded;
+
+    // Tear down FocusTrap when closing. Creation happens in updated()
+    // after the dialog is open so getFocusableElements can find content.
+    if (!this.isPopoverVisible) {
+      this.updateFocusTrap();
+    }
+
     const eventType = event.detail.eventType || "unknown";
     if (!this.isPopoverVisible && this.hasFocus && eventType === "keydown") {
       this.trigger.focus();
@@ -4738,19 +4788,220 @@ class AuroDropdown extends AuroElement {
    * @private
    */
   updateFocusTrap() {
+    // Always clean up existing handlers/traps before setting up new ones
+    // to prevent duplicate listeners on repeated calls.
+    if (this._bibTabHandler) {
+      this.removeEventListener('keydown', this._bibTabHandler);
+      this._bibTabHandler = undefined;
+    }
+
+    if (this.focusTrap) {
+      this.focusTrap.disconnect();
+      this.focusTrap = undefined;
+    }
+
+    // Restore the user-set noHideOnThisFocusLoss value, if we overrode it.
+    if (this._noHideOverridden) {
+      this.noHideOnThisFocusLoss = this._priorNoHide;
+      this._noHideOverridden = false;
+      this._priorNoHide = undefined;
+    }
+
     if (this.isPopoverVisible) {
       if (!this.isBibFullscreen) {
-        // Desktop: show() doesn't trap focus, so use FocusTrap
-        this.focusTrap = new FocusTrap(this.bibContent);
-        this.focusTrap.focusFirstElement();
+        if (this.desktopModal) {
+          // The floater's focus-loss check uses :focus-within, which does not
+          // match the host when focus is on a slotted element projected through
+          // multiple shadow roots. Without this override, focusing a button
+          // inside the bib would be misread as focus leaving the dropdown and
+          // close the bib immediately. desktopModal traps focus inside the
+          // bib and inerts siblings, so suppressing focus-loss dismissal here
+          // is safe — Escape and outside-click still close the bib.
+          this._priorNoHide = this.noHideOnThisFocusLoss;
+          this._noHideOverridden = true;
+          this.noHideOnThisFocusLoss = true;
+
+          // Desktop modal: trap focus only within the bib content.
+          // Can't use FocusTrap on the bib element because keydown events
+          // from slotted content bubble through the dropdown host (light DOM),
+          // not through the bib (shadow projection target). Using FocusTrap
+          // on the dropdown would include the trigger in the tab cycle.
+          // Instead, listen for Tab on the dropdown and manually wrap focus
+          // within the bib's focusable elements.
+          this._bibTabHandler = (event) => {
+            if (event.key !== 'Tab') {
+              return;
+            }
+
+            // Collect focusable elements from the bib content.
+            const focusables = getFocusableElements(this.bibContent);
+
+            // Fallback: try from slotted content directly
+            if (!focusables.length) {
+              const slot = this.shadowRoot.querySelector('.slotContent slot');
+              const assignedNodes = slot.assignedNodes({ flatten: true });
+
+              for (const node of assignedNodes) {
+                if (node.nodeType === Node.ELEMENT_NODE) {
+                  focusables.push(...getFocusableElements(node));
+                }
+              }
+            }
+
+            if (!focusables.length) {
+              return;
+            }
+
+            event.preventDefault();
+
+            const direction = event.shiftKey ? -1 : 1; // eslint-disable-line no-magic-numbers
+
+            // Walk the active element chain through shadow roots
+            const actives = this._getActiveElements();
+
+            let idx = focusables.findIndex((el) => actives.includes(el));
+
+            if (idx === -1) { // eslint-disable-line no-magic-numbers
+              // Focus is not on a known element — move to first/last
+              idx = direction === 1 ? -1 : focusables.length; // eslint-disable-line no-magic-numbers
+            }
+
+            // Try each element in order, skipping any that can't receive focus
+            // (e.g. hidden elements, elements in collapsed sections)
+            for (let index = 0; index < focusables.length; index++) { // eslint-disable-line no-plusplus
+              let nextIdx = idx + direction;
+
+              // Wrap around
+              if (nextIdx < 0) {
+                nextIdx = focusables.length - 1;
+              } else if (nextIdx >= focusables.length) {
+                nextIdx = 0;
+              }
+
+              focusables[nextIdx].focus();
+
+              // Verify focus actually moved to the target
+              const newActives = this._getActiveElements();
+
+              if (newActives.includes(focusables[nextIdx])) {
+                return;
+              }
+
+              // Focus didn't stick — skip this element and try the next
+              idx = nextIdx;
+            }
+          };
+          this.addEventListener('keydown', this._bibTabHandler);
+
+          // Move initial focus into the bib content, matching FocusTrap behavior
+          requestAnimationFrame(() => {
+            const focusables = getFocusableElements(this.bibContent);
+            if (focusables.length) {
+              focusables[0].focus();
+            }
+          });
+        } else {
+          // Normal desktop: use FocusTrap on the bib element.
+          // Defer focusFirstElement to the next frame because the popover
+          // is positioned asynchronously by Floating UI — calling focus()
+          // synchronously here would target elements with zero dimensions
+          // and the focus call would be silently ignored.
+          this.focusTrap = new FocusTrap(this.bibContent);
+          requestAnimationFrame(() => {
+            if (this.focusTrap) {
+              this.focusTrap.focusFirstElement();
+            }
+          });
+        }
       }
       // Fullscreen: showModal() provides native focus trapping
+    }
+  }
+
+  /**
+   * Returns the chain of active (focused) elements through shadow roots.
+   * @private
+   * @returns {Array<HTMLElement>}
+   */
+  _getActiveElements() {
+    let { activeElement } = document;
+    const actives = [activeElement];
+
+    while (activeElement?.shadowRoot?.activeElement) {
+      activeElement = activeElement.shadowRoot.activeElement;
+      actives.push(activeElement);
+    }
+
+    return actives;
+  }
+
+  /**
+   * Sets `inert` on sibling elements of the dropdown's top-level host
+   * so that content outside the dropdown is not interactive while the modal is open.
+   * Walks up through shadow DOM boundaries to find the outermost host element
+   * in the light DOM, then sets `inert` on siblings at each ancestor level
+   * to ensure all page content outside the host subtree is inert.
+   * @private
+   */
+  _setPageInert() {
+    if (this._inertSiblings) {
       return;
     }
 
-    if (this.focusTrap) {
-      this.focusTrap.disconnect();
-      this.focusTrap = undefined;
+    this._inertSiblings = [];
+
+    // Walk up through shadow DOM boundaries to find the topmost host
+    // element in the light DOM. For example, if this dropdown is inside
+    // auro-datepicker's shadow DOM, we walk up to the datepicker element
+    // so we set inert on its siblings — not on the datepicker itself.
+    let host = this;
+    while (host.getRootNode() instanceof ShadowRoot) {
+      host = host.getRootNode().host;
+    }
+
+    // Walk up the ancestor chain, inerting siblings at each level
+    // to ensure the entire page outside the host subtree is inert.
+    // Uses a reference counter (data-auro-inert-count) so multiple
+    // simultaneous modal dropdowns share inert state safely.
+    let current = host;
+    while (current.parentElement) {
+      const parent = current.parentElement;
+      for (const sibling of parent.children) {
+        if (sibling !== current) {
+          const count = parseInt(sibling.dataset.auroInertCount || '0', 10);
+          if (count === 0) {
+            sibling.dataset.auroInertWas = sibling.inert ? 'true' : 'false';
+          }
+          sibling.dataset.auroInertCount = String(count + 1);
+          sibling.inert = true;
+          this._inertSiblings.push(sibling);
+        }
+      }
+      current = parent;
+    }
+  }
+
+  /**
+   * Restores `inert` state on siblings that were tracked by `_setPageInert`.
+   * Uses reference counting so inert is only cleared when the last modal
+   * dropdown releases a given element. Preserves the original inert state
+   * so externally-inerted elements are not inadvertently re-enabled.
+   * @private
+   */
+  _clearPageInert() {
+    if (this._inertSiblings) {
+      for (const sibling of this._inertSiblings) {
+        const count = parseInt(sibling.dataset.auroInertCount || '1', 10) - 1;
+        if (count <= 0) {
+          const wasInert = sibling.dataset.auroInertWas === 'true';
+          delete sibling.dataset.auroInertCount;
+          delete sibling.dataset.auroInertWas;
+          sibling.inert = wasInert;
+        } else {
+          sibling.dataset.auroInertCount = String(count);
+        }
+      }
+      this._inertSiblings = undefined;
     }
   }
 
@@ -4989,6 +5240,7 @@ class AuroDropdown extends AuroElement {
           shape="${this.shape}"
           ?data-show="${this.isPopoverVisible}"
           ?isfullscreen="${this.isBibFullscreen}"
+          ?desktopmodal="${this.desktopModal}"
           .dialogLabel="${this.bibDialogLabel}"
           ${n$2(this.bibElement)}
           >