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

package/components/datepicker/dist/src/auro-datepicker.d.ts

@@ -38,13 +38,10 @@ export class AuroDatePicker extends AuroElement {
     static get properties(): {
         /**
          * Defines whether the component will be on lighter or darker backgrounds.
-         * @property {'default', 'inverse'}
+         * @type {'default' | 'inverse'}
          * @default 'default'
          */
-        appearance: {
-            type: StringConstructor;
-            reflect: boolean;
-        };
+        appearance: "default" | "inverse";
         /**
          * If declared, bib's position will be automatically calculated where to appear.
          * @default false
@@ -53,6 +50,20 @@ export class AuroDatePicker extends AuroElement {
             type: BooleanConstructor;
             reflect: boolean;
         };
+        /**
+         * Array of dates that cannot be selected. Dates should be in ISO format (YYYY-MM-DD).
+         */
+        blackoutDates: {
+            type: ArrayConstructor;
+            reflect: boolean;
+        };
+        /**
+         * Label announced for blackout (disabled but in-range) date cells.
+         */
+        blackoutLabel: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
         /**
          * The last date that may be displayed in the calendar.
          */
@@ -60,6 +71,13 @@ export class AuroDatePicker extends AuroElement {
             type: StringConstructor;
             reflect: boolean;
         };
+        /**
+         * Accessible label for the calendar grid containing the days of the month.
+         */
+        calendarGridLabel: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
         /**
          * The date that will first be visually rendered to the user in the calendar.
          */
@@ -101,24 +119,6 @@ export class AuroDatePicker extends AuroElement {
             type: StringConstructor;
             reflect: boolean;
         };
-        hasFocus: {
-            type: BooleanConstructor;
-            reflect: boolean;
-        };
-        /**
-         * @private
-         */
-        hasValue: {
-            type: BooleanConstructor;
-            reflect: boolean;
-        };
-        /**
-         * @private
-         */
-        hasAllValues: {
-            type: BooleanConstructor;
-            reflect: boolean;
-        };
         /**
          * Specifies the date format. The default is `mm/dd/yyyy`.
          */
@@ -142,6 +142,24 @@ export class AuroDatePicker extends AuroElement {
          * @default 'sm'
          */
         fullscreenBreakpoint: "xs" | "sm" | "md" | "lg" | "xl" | "disabled";
+        /**
+         * @private
+         */
+        hasAllValues: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        hasFocus: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        /**
+         * @private
+         */
+        hasValue: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
         /** Exposes inputmode attribute for input. */
         inputmode: {
             type: StringConstructor;
@@ -176,6 +194,12 @@ export class AuroDatePicker extends AuroElement {
             type: StringConstructor;
             reflect: boolean;
         };
+        /**
+         * @private
+         */
+        monthFirst: {
+            type: BooleanConstructor;
+        };
         /**
          * Names of all 12 months to render in the calendar.
          * When omitted, month names will be automatically populated from the active `locale` (falling back to `en-US`).
@@ -184,17 +208,24 @@ export class AuroDatePicker extends AuroElement {
             type: ArrayConstructor;
         };
         /**
-         * If declared, the bib will NOT flip to an alternate position
-         * when there isn't enough space in the specified `placement`.
+         * Accessible label for the next month navigation button.
          */
-        noFlip: {
-            type: BooleanConstructor;
+        navLabelNextMonth: {
+            type: StringConstructor;
             reflect: boolean;
         };
         /**
-         * If declared, the dropdown will shift its position to avoid being cut off by the viewport.
+         * Accessible label for the previous month navigation button.
          */
-        shift: {
+        navLabelPrevMonth: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        /**
+         * If declared, the bib will NOT flip to an alternate position
+         * when there isn't enough space in the specified `placement`.
+         */
+        noFlip: {
             type: BooleanConstructor;
             reflect: boolean;
         };
@@ -249,6 +280,41 @@ export class AuroDatePicker extends AuroElement {
             type: BooleanConstructor;
             reflect: boolean;
         };
+        /**
+         * Label announced for cells after the range (or after start when no end is selected).
+         */
+        rangeLabelAfterRange: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        /**
+         * Label announced for cells before the range start.
+         */
+        rangeLabelBeforeRange: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        /**
+         * Label announced for the range end date cell.
+         */
+        rangeLabelEnd: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        /**
+         * Label announced for cells within the selected range.
+         */
+        rangeLabelInRange: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        /**
+         * Label announced for the range start date cell.
+         */
+        rangeLabelStart: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
         /**
          * Dates that the user should have for reference as part of their decision making when selecting a date.
          * This should be a JSON string array of ISO date strings (`YYYY-MM-DD`).
@@ -272,6 +338,7 @@ export class AuroDatePicker extends AuroElement {
         };
         /**
          * Custom help text message to display when validity = `customError`.
+         * Also used as the validation message when a blackout date is typed into the input.
          */
         setCustomValidityCustomError: {
             type: StringConstructor;
@@ -294,6 +361,13 @@ export class AuroDatePicker extends AuroElement {
         setCustomValidityValueMissing: {
             type: StringConstructor;
         };
+        /**
+         * If declared, the dropdown will shift its position to avoid being cut off by the viewport.
+         */
+        shift: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
         /**
          * Set true to make datepicker stacked style.
          */
@@ -301,6 +375,15 @@ export class AuroDatePicker extends AuroElement {
             type: BooleanConstructor;
             reflect: boolean;
         };
+        /**
+         * Indicates whether the datepicker is in a dirty state (has been interacted with).
+         * @private
+         */
+        touched: {
+            type: BooleanConstructor;
+            reflect: boolean;
+            attribute: boolean;
+        };
         /**
          * Specifies the `validityState` this element is in.
          */
@@ -320,15 +403,6 @@ export class AuroDatePicker extends AuroElement {
         valueEnd: {
             type: StringConstructor;
         };
-        /**
-         * Indicates whether the datepicker is in a dirty state (has been interacted with).
-         * @private
-         */
-        touched: {
-            type: BooleanConstructor;
-            reflect: boolean;
-            attribute: boolean;
-        };
     };
     static get styles(): import("lit").CSSResult[];
     /**
@@ -359,6 +433,16 @@ export class AuroDatePicker extends AuroElement {
     required: boolean;
     onDark: boolean;
     range: boolean;
+    rangeLabelStart: string;
+    rangeLabelEnd: string;
+    rangeLabelBeforeRange: string;
+    rangeLabelInRange: string;
+    rangeLabelAfterRange: string;
+    blackoutDates: any[];
+    blackoutLabel: string;
+    navLabelPrevMonth: string;
+    navLabelNextMonth: string;
+    calendarGridLabel: string;
     stacked: boolean;
     noValidate: boolean;
     validity: any;
@@ -437,7 +521,7 @@ export class AuroDatePicker extends AuroElement {
     /**
      * Handles click on the clear button.
      * @private
-     * @param {MouseEvent} event - The click event object.
+     * @param {MouseEvent} event - The mouse event from the clear button click.
      * @returns {void}
      */
     private handleClearClick;
@@ -470,7 +554,7 @@ export class AuroDatePicker extends AuroElement {
     /**
      * Common display value wrapper classes.
      * @private
-     * @return {Object} - An object containing the common classes for the display value wrapper.
+     * @returns {Object} Class map for Lit's classMap directive.
      */
     private get commonDisplayValueWrapperClasses();
     /**
@@ -582,6 +666,13 @@ export class AuroDatePicker extends AuroElement {
      * @returns {void}
      */
     private notifyMonthChanged;
+    /**
+     * Attempts to focus the active calendar cell using a rAF retry loop.
+     * Shared by both fullscreen and desktop open paths.
+     * @private
+     * @returns {void}
+     */
+    private focusActiveCellWhenReady;
     /**
      * Binds all behavior needed to the dropdown after rendering.
      * @private
@@ -589,6 +680,7 @@ export class AuroDatePicker extends AuroElement {
      */
     private configureDropdown;
     dropdown: any;
+    centralDate: any;
     /**
      * Binds all behavior needed to the input after rendering.
      * @private
@@ -656,6 +748,13 @@ export class AuroDatePicker extends AuroElement {
      * @returns {void}
      */
     clear(): void;
+    /**
+     * Checks whether a formatted date string matches a blackout date.
+     * @private
+     * @param {string} dateStr - A date string in the component's configured format.
+     * @returns {boolean} True if the date is in the blackoutDates list.
+     */
+    private isBlackoutDate;
     /**
      * Validates value.
      * @param {boolean} [force=false] - Whether to force validation.
@@ -672,7 +771,7 @@ export class AuroDatePicker extends AuroElement {
      */
     get hasError(): boolean;
     /**
-     * lifecycle method to check if the locale is valid.
+     * Lifecycle method to check if the locale is valid.
      * @ignore
      * @param {Map} changedProperties - The map of properties that have changed since the last update.
      * @returns {void}
@@ -681,6 +780,7 @@ export class AuroDatePicker extends AuroElement {
     format: string | undefined;
     updated(changedProperties: any): void;
     previousTabIndex: string | null | undefined;
+    wasCellClick: boolean | undefined;
     /**
      * Handles the transfer of content between slots in the component.
      *

package/components/datepicker/dist/src/datepickerKeyboardStrategy.d.ts

@@ -1,3 +1,5 @@
-export namespace datepickerKeyboardStrategy {
-    function Escape(component: any, evt: any): void;
-}
+export const datepickerKeyboardStrategy: {
+    Escape(component: any, evt: any, ctx: any): void;
+    Enter(component: any, evt: any, ctx: any): void;
+    ' '(component: any, evt: any, ctx: any): void;
+};

package/components/dropdown/demo/accessibility.md

@@ -28,12 +28,23 @@
 </ol>
 </section>
 <section>
+<auro-header level="2" id="desktopModal">Desktop Modal</auro-header>
+<p>When the <code>desktopModal</code> attribute is set, the dropdown behaves as a modal dialog on desktop viewports:</p>
+<ul>
+<li>All sibling elements on the page are marked <code>inert</code>, preventing interaction with content outside the dropdown.</li>
+<li>Focus is trapped within the bib content using a Tab-key handler.</li>
+<li>The <code>inert</code> state and focus trap are automatically cleaned up when the bib is closed or the component is disconnected.</li>
+</ul>
+<p>In fullscreen mode, the native <code>&lt;dialog&gt;</code> <code>showModal()</code> API provides equivalent behavior, so <code>desktopModal</code> only applies to desktop-sized viewports.</p>
+</section>
+<section>
 <auro-header level="2" id="tabBehavior">Tab Behavior</auro-header>
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/tabindex.md) -->
 <!-- The below content is automatically added from ./../docs/partials/tabindex.md -->
 <p>The trigger is a focusable element and participates in the standard tab order, responding to <code>Tab</code> and <code>Shift+Tab</code> key events per <auro-hyperlink href="https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex">native browser behavior</auro-hyperlink>, i.e., these keys step through the browser tabindex sequence.</p>
 <p>When the component is <code>disabled</code> it is removed from the <code>tabindex</code> sequence. VoiceOver's virtual cursor <em>(swipe navigation)</em> can still encounter the component, but standard keyboard <code>Tab</code> navigation skips it.</p>
 <p>When the bib is collapsed, the bib content is excluded from the tab sequence. When <strong>expanded</strong>, focusable elements within the bib content are included in the natural tab order. In fullscreen mode, focus is trapped within the bib, and the tab sequence cycles through the bib content focusable elements until the bib is closed or the viewport no longer meets the fullscreen condition and is rendered as a popover.</p>
+<p>When the <code>desktopModal</code> attribute is set, focus is also trapped within the bib on desktop viewports. All sibling elements on the page are marked <code>inert</code>, preventing interaction with content outside the dropdown until it is closed.</p>
 <!-- AURO-GENERATED-CONTENT:END -->
 </section>
 <section>

package/components/dropdown/demo/api.md

@@ -13,6 +13,7 @@ The `auro-dropdown` element provides a way to place content in a bib that can be
 | `appearance`              | `appearance`              | `'default' \| 'inverse'`                         | "'default'"      | Defines whether the component will be on lighter or darker backgrounds. |
 | `autoPlacement`           | `autoPlacement`           | `boolean`                                        |                  | If declared, bib's position will be automatically calculated where to appear. |
 | `chevron`                 | `chevron`                 | `boolean`                                        |                  | If declared, the dropdown displays a chevron on the right. |
+| `desktopModal`            | `desktopModal`            | `boolean`                                        |                  | If declared, the dropdown will behave as a modal dialog when in a desktop viewport size. |
 | `disableEventShow`        | `disableEventShow`        | `boolean`                                        |                  | If declared, the dropdown will only show by calling the API .show() public method. |
 | `disableKeyboardHandling` | `disableKeyboardHandling` | `boolean`                                        |                  | If declared, the dropdown will not handle keyboard events and will require the consumer to manage this behavior. |
 | `disabled`                | `disabled`                | `boolean`                                        |                  | If declared, the dropdown is not interactive.    |

package/components/dropdown/demo/css-only.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/css-only.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-dropdown | CSS only</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-dropdown'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('./css-only.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/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>