@aurodesignsystem-dev/auro-formkit 0.0.0-pr1488.2 → 0.0.0-pr1489.0

package/components/combobox/demo/index.min.js

@@ -4662,7 +4662,7 @@ function applyKeyboardStrategy(component, strategy, options = {}) {
   });
 }
 
-var styleCss$2$1 = i$7`: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$1 = i$7`: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$1 = i$7`.container{background-color:var(--ds-auro-dropdownbib-container-color);box-shadow:var(--ds-auro-dropdownbib-boxshadow-color);color:var(--ds-auro-dropdownbib-text-color)}`;
 
@@ -5293,7 +5293,7 @@ let AuroHelpText$2 = class AuroHelpText extends i$4 {
   }
 };
 
-var formkitVersion$2 = '202606011708';
+var formkitVersion$2 = '202606011856';
 
 let AuroElement$2 = class AuroElement extends i$4 {
   static get properties() {
@@ -5473,6 +5473,7 @@ class AuroDropdown extends AuroElement$2 {
   _intializeDefaults() {
     this.appearance = 'default';
     this.chevron = false;
+    this.desktopModal = false;
     this.disabled = false;
     this.disableKeyboardHandling = false;
     this.error = false;
@@ -5653,6 +5654,14 @@ class AuroDropdown extends AuroElement$2 {
         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.
        */
@@ -5940,6 +5949,15 @@ class AuroDropdown extends AuroElement$2 {
 
   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();
@@ -5967,19 +5985,45 @@ class AuroDropdown extends AuroElement$2 {
       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();
+      }
     }
   }
 
@@ -5989,8 +6033,14 @@ class AuroDropdown extends AuroElement$2 {
    * @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();
@@ -6089,19 +6139,178 @@ class AuroDropdown extends AuroElement$2 {
    * @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;
+    }
+
     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) {
+          // 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 ? 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
+          this.focusTrap = new FocusTrap(this.bibContent);
+          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.
+    let current = host;
+    while (current.parentElement) {
+      const parent = current.parentElement;
+      for (const sibling of parent.children) {
+        if (sibling !== current) {
+          this._inertSiblings.push({ element: sibling, wasInert: sibling.inert });
+          sibling.inert = true;
+        }
+      }
+      current = parent;
+    }
+  }
+
+  /**
+   * Restores `inert` state on siblings that were tracked by `_setPageInert`.
+   * Preserves the previous inert state so externally-inerted elements are
+   * not inadvertently re-enabled.
+   * @private
+   */
+  _clearPageInert() {
+    if (this._inertSiblings) {
+      for (const entry of this._inertSiblings) {
+        entry.element.inert = entry.wasInert;
+      }
+      this._inertSiblings = undefined;
     }
   }
 
@@ -6340,6 +6549,7 @@ class AuroDropdown extends AuroElement$2 {
           shape="${this.shape}"
           ?data-show="${this.isPopoverVisible}"
           ?isfullscreen="${this.isBibFullscreen}"
+          ?desktopmodal="${this.desktopModal}"
           .dialogLabel="${this.bibDialogLabel}"
           ${n$2(this.bibElement)}
           >
@@ -13045,7 +13255,7 @@ let AuroHelpText$1 = class AuroHelpText extends i$4 {
   }
 };
 
-var formkitVersion$1 = '202606011708';
+var formkitVersion$1 = '202606011856';
 
 // Copyright (c) 2025 Alaska Airlines. All right reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.
@@ -13999,6 +14209,14 @@ class AuroBibtemplate extends i$4 {
       large: {
         type: Boolean,
         reflect: true
+      },
+
+      /**
+       * If declared, the footer slot will be rendered even when not in fullscreen mode.
+       */
+      showFooter: {
+        type: Boolean,
+        reflect: true
       }
     };
   }
@@ -14101,7 +14319,7 @@ class AuroBibtemplate extends i$4 {
           <slot></slot>
         </div>
 
-      ${this.isFullscreen ? u$7`
+      ${this.isFullscreen || this.showFooter ? u$7`
         <div id="footerContainer">
           <slot name="footer"></slot>
         </div>` : null}
@@ -14110,7 +14328,7 @@ class AuroBibtemplate extends i$4 {
   }
 }
 
-var formkitVersion = '202606011708';
+var formkitVersion = '202606011856';
 
 var styleCss$3 = i$7`.util_displayInline{display:inline}.util_displayInlineBlock{display:inline-block}.util_displayBlock{display:block}.util_displayFlex{display:flex}.util_displayHidden{display:none}.util_displayHiddenVisually{position:absolute;overflow:hidden;clip:rect(1px, 1px, 1px, 1px);width:1px;height:1px;padding:0;border:0}:host{display:block;text-align:left}:host [auro-dropdown]{--ds-auro-dropdown-trigger-background-color: transparent}:host #inputInBib::part(wrapper){box-shadow:none}:host #inputInBib::part(accent-left){display:none}:host([layout*=classic]) [auro-input]{width:100%}:host([layout*=classic]) [auro-input]::part(helpText){display:none}:host([layout*=classic]) #slotHolder{display:none}`;
 

package/components/combobox/demo/pages.json

@@ -1 +1 @@
-["accessibility.md","api.md","customize.md","design.md","getting-started.md","index.md","keyboard-behavior.md","voiceover.md","readme.md"]
+["accessibility.md","api.md","customize.md","design.md","getting-started.md","index.md","keyboard-behavior.md","voiceover.md","why-combobox.md","readme.md"]

package/components/combobox/demo/why-combobox.html

@@ -0,0 +1,57 @@
+<!--
+  Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
+  See LICENSE in the project root for license information.
+
+  HTML in this document is standardized and NOT to be edited.
+  All demo code should be added/edited in ./demo/why-combobox.md
+
+  With the exception of adding custom elements if needed for the demo.
+
+  ----------------------- DO NOT EDIT -----------------------------
+
+-->
+
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Auro Web Component Demo | auro-combobox | Why auro-combobox</title>
+
+    <!-- highlight.js Stylesheet -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.9.0/build/styles/github.min.css"/>
+
+    <!-- Legacy reference is still needed to support auro-combobox's use of legacy token values at this time -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/legacy/auro-classic/CSSCustomProperties.css"/>
+
+    <!-- Design Token Alaska Theme -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/themes/alaska/CSSCustomProperties--alaska.min.css"/>
+
+    <!-- Webcore Stylesheet Alaska Theme -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/bundled/themes/alaska.global.min.css" />
+
+    <!-- Demo Specific Styles -->
+    <link rel="stylesheet" type="text/css" href="./styles.min.css" />
+    <style>
+      table {
+        --ds-color-container-secondary-default: transparent;
+      }
+
+      tr:not(:last-of-type) {
+        border-bottom: 1px solid var(--ds-color-border-tertiary-default);
+      }
+    </style>
+  </head>
+  <body class="auro-markdown">
+    <main></main>
+
+    <script type="module">
+      import { renderPage } from './demo-support.min.js';
+      await renderPage('./why-combobox.md');
+    </script>
+
+    <!-- If additional elements are needed for the demo, add them here. -->
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-header@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-hyperlink@latest/+esm" type="module"></script>
+  </body>
+</html>

package/components/combobox/demo/why-combobox.md

@@ -0,0 +1,113 @@
+<auro-header level="1" id="overview">Why auro-combobox?</auro-header>
+<p>The native <code>&lt;input list&gt;</code> with <code>&lt;datalist&gt;</code> provides a basic autocomplete experience, but it cannot be styled, has no concept of required selection, and offers no mobile-friendly layout. <code>auro-combobox</code> is a fully featured autocomplete and selection component designed for real-world use.</p>
+<auro-header level="2" id="accessibility">Accessibility</auro-header>
+<p>Native <code>&lt;datalist&gt;</code> support varies between browsers. Some announce suggestion counts, others do not. Keyboard behavior is inconsistent, and there is no standard way to communicate selection state to screen readers.</p>
+<p><code>auro-combobox</code> provides:</p>
+<ul>
+<li><strong>ARIA combobox pattern</strong> — The input carries <code>aria-expanded</code>, <code>aria-owns</code>, and <code>aria-haspopup</code> to properly describe the relationship between the input and the suggestions list.</li>
+<li><strong>Active descendant tracking</strong> — <code>aria-activedescendant</code> moves with keyboard navigation so screen readers announce the highlighted option without moving DOM focus.</li>
+<li><strong>Live region announcements</strong> — Selections are announced via <code>aria-live="polite"</code>, and validation errors use <code>aria-live="assertive"</code>.</li>
+<li><strong>Full keyboard navigation</strong> — Arrow keys navigate options, Enter selects, Escape closes, Home/End jump to boundaries. A dedicated keyboard strategy handles all interactions.</li>
+</ul>
+<auro-header level="2" id="dualBehaviorModes">Dual behavior modes</auro-header>
+<p>Native <code>&lt;datalist&gt;</code> always allows freeform input. There is no way to restrict the user to only the provided options.</p>
+<p><code>auro-combobox</code> supports two modes:</p>
+<ul>
+<li><strong>Suggestion mode</strong> (default) — The user can type any value. Suggestions are offered but not required.</li>
+<li><strong>Filter mode</strong> — The user must select from the available options. Typed text filters the list but cannot be submitted as a value. Validation enforces this constraint.</li>
+</ul>
+<auro-header level="2" id="realtimeFiltering">Real-time filtering</auro-header>
+<p><code>&lt;datalist&gt;</code> filtering is browser-controlled and cannot be customized. Some browsers match from the start of the option text, others match anywhere.</p>
+<p><code>auro-combobox</code> filters options as the user types, with full control:</p>
+<ul>
+<li><code>noFilter</code> disables filtering to show all options regardless of input</li>
+<li><code>matchWord</code> highlights the matched portion of each option</li>
+<li><code>persistInput</code> keeps the filter text visible after selection</li>
+</ul>
+<auro-header level="2" id="responsiveLayout">Responsive layout</auro-header>
+<p>Native <code>&lt;datalist&gt;</code> renders a small browser-controlled popup that cannot be repositioned or resized.</p>
+<p><code>auro-combobox</code> adapts to the viewport:</p>
+<ul>
+<li><strong>Desktop</strong> — Suggestions appear as a positioned dropdown using Floating UI, with configurable placement, offset, flip, and shift behavior</li>
+<li><strong>Mobile</strong> — Suggestions open in a fullscreen dialog via <code>showModal()</code>, with a configurable breakpoint (<code>fullscreenBreakpoint</code>)</li>
+<li><strong>Width matching</strong> — The dropdown can match the input width or size independently</li>
+</ul>
+<auro-header level="2" id="validation">Validation</auro-header>
+<p>Native <code>&lt;datalist&gt;</code> has no built-in validation beyond standard <code>required</code>.</p>
+<p><code>auro-combobox</code> integrates with the Auro form validation system:</p>
+<ul>
+<li>Required field validation with mode-aware messaging (separate messages for suggestion vs. filter mode)</li>
+<li>Custom error messages per validity state (<code>setCustomValidityCustomError</code>, <code>setCustomValidityValueMissing</code>, <code>setCustomValidityValueMissingFilter</code>)</li>
+<li>Validation on blur with <code>noValidate</code> opt-out</li>
+<li>Error display via help text with <code>role="alert"</code></li>
+</ul>
+<auro-header level="2" id="inputMasking">Input masking</auro-header>
+<p><code>&lt;datalist&gt;</code> inputs have no formatting support.</p>
+<p><code>auro-combobox</code> supports input masks via the <code>format</code> attribute, enabling structured input (e.g., dates, phone numbers) while still offering suggestions.</p>
+<auro-header level="2" id="designSystemIntegration">Design system integration</auro-header>
+<p><code>&lt;datalist&gt;</code> styling is entirely browser-controlled. The popup cannot be themed, and option rendering is limited to plain text.</p>
+<p><code>auro-combobox</code> is built with the Auro Design System:</p>
+<ul>
+<li>Three layout options: classic, emphasized, and snowflake</li>
+<li>Light and dark theme support (<code>appearance</code>)</li>
+<li>Checkmarks on selected options</li>
+<li>Rich HTML content in options (icons, descriptions, nested structure)</li>
+<li>CSS <code>::part()</code> selectors for styling</li>
+</ul>
+<auro-header level="2" id="summary">Summary</auro-header>
+<table>
+<thead>
+<tr>
+<th>Capability</th>
+<th><code>&lt;input list&gt;</code> + <code>&lt;datalist&gt;</code></th>
+<th><code>auro-combobox</code></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Restrict to options only</td>
+<td>No</td>
+<td>Yes (filter mode)</td>
+</tr>
+<tr>
+<td>Real-time filtering control</td>
+<td>Browser-controlled</td>
+<td>Fully configurable</td>
+</tr>
+<tr>
+<td>Keyboard navigation</td>
+<td>Inconsistent</td>
+<td>Full arrow/Enter/Escape/Home/End</td>
+</tr>
+<tr>
+<td>Screen reader announcements</td>
+<td>Inconsistent</td>
+<td>Live regions and active descendant</td>
+</tr>
+<tr>
+<td>Mobile fullscreen</td>
+<td>No</td>
+<td>Automatic at breakpoint</td>
+</tr>
+<tr>
+<td>Input masking</td>
+<td>No</td>
+<td>Yes (format attribute)</td>
+</tr>
+<tr>
+<td>Custom validation messages</td>
+<td>No</td>
+<td>Per-constraint messages</td>
+</tr>
+<tr>
+<td>Rich option content</td>
+<td>Plain text only</td>
+<td>Full HTML</td>
+</tr>
+<tr>
+<td>Theming</td>
+<td>No</td>
+<td>Three layouts + appearance modes</td>
+</tr>
+</tbody>
+</table>