@aurodesignsystem-dev/auro-formkit 0.0.0-pr1448.0 → 0.0.0-pr1451.1

package/components/radio/demo/api.min.js

@@ -1645,7 +1645,7 @@ class AuroHelpText extends i$2 {
   }
 }
 
-var formkitVersion = '202604231640';
+var formkitVersion = '202604232250';
 
 // Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.

package/components/radio/demo/index.md

@@ -1,7 +1,7 @@
 <!--
- THIS PAGE'S CONTENT SHOULD BE KEPT MINIMAL.
- ONLY ADD EXAMPLES THAT ARE TRULY NECESSARY FOR THE INDEX PAGE — THE BASIC EXAMPLE IS USUALLY ENOUGH.
- ALL OTHER EXAMPLES SHOULD GO IN THE API DOCUMENTATION.
+THIS PAGE'S CONTENT SHOULD BE KEPT MINIMAL.
+ONLY ADD EXAMPLES THAT ARE TRULY NECESSARY FOR THE INDEX PAGE — THE BASIC EXAMPLE IS USUALLY ENOUGH.
+ALL OTHER EXAMPLES SHOULD GO IN THE API DOCUMENTATION.
 -->
 
 # Radio
@@ -27,47 +27,43 @@ The following examples illustrate fully functional `<auro-radio>` elements wrapp
 ### Basic Radio
 
 <div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/basic-standalone.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/basic-standalone.html -->
-  <auro-radio id="basicRadio1" label="Yes" name="radioDemo" value="yes"></auro-radio>
-  <!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/basic-standalone.html) -->
+<!-- The below content is automatically added from ./../apiExamples/basic-standalone.html -->
+<auro-radio id="basicRadio1" label="Yes" name="radioDemo" value="yes"></auro-radio>
+<!-- AURO-GENERATED-CONTENT:END -->
 </div>
 <auro-accordion alignRight>
-  <span slot="trigger">See code</span>
+<span slot="trigger">See code</span>
 <!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/basic-standalone.html) -->
 <!-- The below code snippet is automatically added from ./../apiExamples/basic-standalone.html -->
 
-```html
-<auro-radio id="basicRadio1" label="Yes" name="radioDemo" value="yes"></auro-radio>
-```
+<pre class="language-html"><code class="language-html">&lt;auro-radio id="basicRadio1" label="Yes" name="radioDemo" value="yes"&gt;&lt;/auro-radio&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
 ### Basic Radio Group
 
 <div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/basic.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/basic.html -->
-  <auro-radio-group>
-    <span slot="legend">Form label goes here</span>
-    <auro-radio id="basicGroupRadio1" label="Yes" name="radioDemo" value="yes"></auro-radio>
-    <auro-radio id="basicGroupRadio2" label="No" name="radioDemo" value="no"></auro-radio>
-    <auro-radio id="basicGroupRadio3" label="Maybe" name="radioDemo" value="maybe"></auro-radio>
-  </auro-radio-group>
-  <!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/basic.html) -->
+<!-- The below content is automatically added from ./../apiExamples/basic.html -->
+<auro-radio-group>
+<span slot="legend">Form label goes here</span>
+<auro-radio id="basicGroupRadio1" label="Yes" name="radioDemo" value="yes"></auro-radio>
+<auro-radio id="basicGroupRadio2" label="No" name="radioDemo" value="no"></auro-radio>
+<auro-radio id="basicGroupRadio3" label="Maybe" name="radioDemo" value="maybe"></auro-radio>
+</auro-radio-group>
+<!-- AURO-GENERATED-CONTENT:END -->
 </div>
 <auro-accordion alignRight>
-  <span slot="trigger">See code</span>
+<span slot="trigger">See code</span>
 <!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/basic.html) -->
 <!-- The below code snippet is automatically added from ./../apiExamples/basic.html -->
 
-```html
-<auro-radio-group>
-  <span slot="legend">Form label goes here</span>
-  <auro-radio id="basicGroupRadio1" label="Yes" name="radioDemo" value="yes"></auro-radio>
-  <auro-radio id="basicGroupRadio2" label="No" name="radioDemo" value="no"></auro-radio>
-  <auro-radio id="basicGroupRadio3" label="Maybe" name="radioDemo" value="maybe"></auro-radio>
-</auro-radio-group>
-```
+<pre class="language-html"><code class="language-html">&lt;auro-radio-group&gt;
+  &lt;span slot="legend"&gt;Form label goes here&lt;/span&gt;
+  &lt;auro-radio id="basicGroupRadio1" label="Yes" name="radioDemo" value="yes"&gt;&lt;/auro-radio&gt;
+  &lt;auro-radio id="basicGroupRadio2" label="No" name="radioDemo" value="no"&gt;&lt;/auro-radio&gt;
+  &lt;auro-radio id="basicGroupRadio3" label="Maybe" name="radioDemo" value="maybe"&gt;&lt;/auro-radio&gt;
+&lt;/auro-radio-group&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>

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

@@ -1620,7 +1620,7 @@ class AuroHelpText extends i$2 {
   }
 }
 
-var formkitVersion = '202604231640';
+var formkitVersion = '202604232250';
 
 // Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.

package/components/radio/demo/keyboard-behavior.md

@@ -0,0 +1,72 @@
+<auro-header level="1" id="overview">Radio - Keyboard Behavior</auro-header>
+<div class="contentWrapper">
+<div class="mainContent">
+<div class="scrollWrapper">
+<auro-header level="2" id="tabBehavior">Tab Behavior</auro-header>
+<p>Within an <code>&lt;auro-radio-group&gt;</code>, the currently selected radio (or the first enabled radio if none is selected) participates in the browser's default <code>tabindex</code> sequence. Arrow keys move focus and selection between radios within the group.</p>
+<p>When the component is <code>disabled</code> it is removed from the <code>tabindex</code> sequence.</p>
+<auro-header level="2" id="keyEvents">Key Events</auro-header>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/keyEvents.md) -->
+<!-- The below content is automatically added from ./../docs/partials/keyEvents.md -->
+<table>
+<thead>
+<tr>
+<th>Key</th>
+<th>Modifier</th>
+<th>Current State</th>
+<th>Focus Element</th>
+<th>Behavior</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Space</td>
+<td>-</td>
+<td>Not disabled</td>
+<td>Radio element</td>
+<td>
+Selects the radio at the current focus index.
+</td>
+</tr>
+<tr>
+<td>ArrowDown</td>
+<td>-</td>
+<td>Focus within the radio group</td>
+<td>Any radio in the group</td>
+<td>
+Selects and focuses the next enabled radio. Wraps from last to first. Skips disabled items. Calls <code>preventDefault()</code>.
+</td>
+</tr>
+<tr>
+<td>ArrowRight</td>
+<td>-</td>
+<td>Focus within the radio group</td>
+<td>Any radio in the group</td>
+<td>
+Same as ArrowDown.
+</td>
+</tr>
+<tr>
+<td>ArrowUp</td>
+<td>-</td>
+<td>Focus within the radio group</td>
+<td>Any radio in the group</td>
+<td>
+Selects and focuses the previous enabled radio. Wraps from first to last. Skips disabled items. Calls <code>preventDefault()</code>.
+</td>
+</tr>
+<tr>
+<td>ArrowLeft</td>
+<td>-</td>
+<td>Focus within the radio group</td>
+<td>Any radio in the group</td>
+<td>
+Same as ArrowUp.
+</td>
+</tr>
+</tbody>
+</table>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+</div>
+</div>

package/components/radio/demo/readme.md

@@ -46,9 +46,7 @@ The following examples illustrate fully functional `<auro-radio>` elements wrapp
 
 #### NPM Installation
 
-```shell
-$ npm i @aurodesignsystem/auro-formkit
-```
+<pre class="language-shell"><code class="language-shell">$ npm i @aurodesignsystem/auro-formkit</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=../../docs/templates/gettingStarted.md) -->
 <!-- The below content is automatically added from ../../docs/templates/gettingStarted.md -->
@@ -57,13 +55,11 @@ $ npm i @aurodesignsystem/auro-formkit
 
 When using TypeScript set `moduleResolution` to `bundler`, add the following to your `tsconfig.json`:
 
-```json
-{
+<pre class="language-json"><code class="language-json">{
     "compilerOptions": {
         "moduleResolution": "bundler"
     }
-}
-```
+}</code></pre>
 
 This configuration enables proper module resolution for the component's TypeScript files.
 <!-- AURO-GENERATED-CONTENT:END -->
@@ -74,9 +70,7 @@ This configuration enables proper module resolution for the component's TypeScri
 <!-- The below content is automatically added from ../../docs/templates/bundleInstallDescription.md -->
 In cases where the project is not able to process JS assets, there are pre-processed assets available for use. Legacy browsers such as IE11 are no longer supported.
 
-```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@latest/auro-radio/+esm"></script>
-```
+<pre class="language-html"><code class="language-html">&lt;script type="module" src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@latest/auro-radio/+esm"&gt;&lt;/script&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 
 ## Formkit Development
@@ -90,9 +84,7 @@ Running the `dev` command will open a `localhost` development server for all com
 
 To only develop a single component, use the `--filter` flag:
 
-```shell
-npx turbo dev --filter=@aurodesignsystem/auro-input
-```
+<pre class="language-shell"><code class="language-shell">npx turbo dev --filter=@aurodesignsystem/auro-input</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/customRegistration.md) -->
 <!-- The below content is automatically added from ./docs/partials/customRegistration.md -->
@@ -107,35 +99,31 @@ However, if you need to load multiple versions of the same component on a single
 
 You can do this by importing only the component class and using the `register(name)` method with a unique name:
 
-```js
-// Import the class only
+<pre class="language-js"><code class="language-js">// Import the class only
 import { AuroRadio, AuroRadioGroup } from '@aurodesignsystem/auro-formkit/auro-radio/class';
-
+​
 // Register with a custom name if desired
 AuroRadio.register('custom-radio');
-AuroRadioGroup.register('custom-radio-group');
-```
+AuroRadioGroup.register('custom-radio-group');</code></pre>
 
 This will create a new custom element `<custom-radio>` and `<custom-radio-group>` that behaves exactly like `<auro-radio>` and `<auro-radio-group>`, allowing both to coexist on the same page without interfering with each other.
 
 <div class="exampleWrapper exampleWrapper--flex">
-  <custom-radio-group>
-    <span slot="legend">Form label goes here</span>
-    <custom-radio id="customRadio1" label="Yes" name="radioDemo" value="yes"></custom-radio>
-    <custom-radio id="customRadio2" label="No" name="radioDemo" value="no"></custom-radio>
-    <custom-radio id="customRadio3" label="Maybe" name="radioDemo" value="maybe"></custom-radio>
-  </custom-radio-group>
+<custom-radio-group>
+<span slot="legend">Form label goes here</span>
+<custom-radio id="customRadio1" label="Yes" name="radioDemo" value="yes"></custom-radio>
+<custom-radio id="customRadio2" label="No" name="radioDemo" value="no"></custom-radio>
+<custom-radio id="customRadio3" label="Maybe" name="radioDemo" value="maybe"></custom-radio>
+</custom-radio-group>
 </div>
 <auro-accordion alignRight>
-  <span slot="trigger">See code</span>
+<span slot="trigger">See code</span>
 
-```html
-  <custom-radio-group>
-    <span slot="legend">Form label goes here</span>
-    <custom-radio id="customRadio1" label="Yes" name="radioDemo" value="yes"></custom-radio>
-    <custom-radio id="customRadio2" label="No" name="radioDemo" value="no"></custom-radio>
-    <custom-radio id="customRadio3" label="Maybe" name="radioDemo" value="maybe"></custom-radio>
-  </custom-radio-group>
-```
+<pre class="language-html"><code class="language-html">&lt;custom-radio-group&gt;
+  &lt;span slot="legend"&gt;Form label goes here&lt;/span&gt;
+  &lt;custom-radio id="customRadio1" label="Yes" name="radioDemo" value="yes"&gt;&lt;/custom-radio&gt;
+  &lt;custom-radio id="customRadio2" label="No" name="radioDemo" value="no"&gt;&lt;/custom-radio&gt;
+  &lt;custom-radio id="customRadio3" label="Maybe" name="radioDemo" value="maybe"&gt;&lt;/custom-radio&gt;
+&lt;/custom-radio-group&gt;</code></pre>
 </auro-accordion>
 <!-- AURO-GENERATED-CONTENT:END -->

package/components/radio/dist/auro-radio-group.d.ts

@@ -125,16 +125,16 @@ export class AuroRadioGroup extends LitElement {
      */
     static register(name?: string): void;
     _initializeDefaults(): void;
-    appearance: string;
-    disabled: boolean;
-    horizontal: boolean;
-    required: boolean;
+    appearance: string | undefined;
+    disabled: boolean | undefined;
+    horizontal: boolean | undefined;
+    required: boolean | undefined;
     validity: any;
     value: any;
-    optionSelected: EventTarget;
-    onDark: boolean;
-    touched: boolean;
-    hasLegend: boolean;
+    optionSelected: EventTarget | null | undefined;
+    onDark: boolean | undefined;
+    touched: boolean | undefined;
+    hasLegend: boolean | undefined;
     /**
      * @private
      */
@@ -197,7 +197,7 @@ export class AuroRadioGroup extends LitElement {
      * @returns {void}
      */
     private handleItems;
-    items: Element[];
+    items: Element[] | undefined;
     /**
      * Method for handling slot content changes.
      * @private

package/components/radio/dist/auro-radio.d.ts

@@ -120,13 +120,13 @@ export class AuroRadio extends LitElement {
      */
     static register(name?: string): void;
     _initializeDefaults(): void;
-    appearance: string;
+    appearance: string | undefined;
     checked: any;
-    disabled: boolean;
-    required: boolean;
-    error: boolean;
-    onDark: boolean;
-    touched: boolean;
+    disabled: boolean | undefined;
+    required: boolean | undefined;
+    error: boolean | undefined;
+    onDark: boolean | undefined;
+    touched: boolean | undefined;
     /**
      * @private
      */
@@ -173,8 +173,8 @@ export class AuroRadio extends LitElement {
      */
     private isRequired;
     firstUpdated(): void;
-    input: HTMLInputElement;
-    inputId: string;
+    input: HTMLInputElement | null | undefined;
+    inputId: string | undefined;
     render(): import("lit-html").TemplateResult<1>;
 }
 import { LitElement } from "lit";

package/components/radio/dist/index.js

@@ -1573,7 +1573,7 @@ class AuroHelpText extends LitElement {
   }
 }
 
-var formkitVersion = '202604231640';
+var formkitVersion = '202604232250';
 
 // Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.

package/components/radio/dist/registered.js

@@ -1573,7 +1573,7 @@ class AuroHelpText extends LitElement {
   }
 }
 
-var formkitVersion = '202604231640';
+var formkitVersion = '202604232250';
 
 // Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.

package/components/select/README.md

@@ -21,7 +21,18 @@ The following sections are editable by making changes to the following files:
 
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/description.md) -->
 <!-- The below content is automatically added from ./docs/partials/description.md -->
-`<auro-select>` is a combination <auro-hyperlink href="https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements">HTML custom element</auro-hyperlink> that consists of a pre-defined trigger element, `<auro-menu>` for the panel content. The `<auro-select>` element presents a menu of options. The options within the menu are represented by `<auro-menu>` and `<auro-menuoption>` elements. You can pre-select options for the user with the `selected` attribute as part of the `<auro-menuoption>` API.
+<p>The component is a combination <auro-hyperlink href="https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements">HTML custom elements</auro-hyperlink> that consists of a pre-defined trigger element, <code>&lt;auro-menu&gt;</code> for the panel content. The <code>&lt;auro-select&gt;</code> element presents a menu of options. The options within the menu are represented by <code>&lt;auro-menu&gt;</code> and <code>&lt;auro-menuoption&gt;</code> elements. You can pre-select options for the user with the `selected` attribute as part of the <code>&lt;auro-menuoption&gt;</code> API.</p>
+<p>The component is used to create a drop-down list for user input within a form. It acts as a container for options.</p>
+<p>Key features:</p>
+<ul>
+  <li>Preset values</li>
+  <li>Mark as required when in a form</li>
+  <li>Disable individual options or the entire component</li>
+  <li>Enable multi-select</li>
+  <li>Separate options into groups with dividers</li>
+  <li>Group options into nested levels</li>
+  <li>Autocomplete</li>
+</ul>
 <!-- AURO-GENERATED-CONTENT:END -->
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/readmeAddlInfo.md) -->
 <!-- The below content is automatically added from ./docs/partials/readmeAddlInfo.md -->

package/components/select/demo/accessibility.html

@@ -0,0 +1,65 @@
+<!--
+  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/accessibility.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-select | Accessibility</title>
+
+    <!-- Prism.js Stylesheet -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/prismjs@1.24.1/themes/prism.css"/>
+
+    <!-- Legacy reference is still needed to support auro-select'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="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/demoWrapper.css" />
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/elementDemoStyles.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 'https://cdn.jsdelivr.net/npm/marked@latest/marked.min.js';
+      import 'https://cdn.jsdelivr.net/npm/prismjs@latest/prism.js';
+      fetch('./accessibility.md')
+        .then((response) => response.text())
+        .then((text) => {
+          const rawHtml = marked.parse(text);
+          document.querySelector('main').innerHTML = rawHtml;
+          Prism.highlightAll();
+        });
+    </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/select/demo/accessibility.md

@@ -0,0 +1,76 @@
+<auro-header level="1" id="overview">Select - Accessibility</auro-header>
+<div class="contentWrapper">
+<div class="mainContent">
+<div class="scrollWrapper">
+The `auro-select` component follows the <a href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/" target="_blank">W3C APG Select-Only Combobox</a> pattern. This page documents the ARIA semantics, screen reader announcements, and other accessibility behaviors built into the component.
+
+For keyboard interaction details, see the <a href="./keyboardBehavior.html">Keyboard Behavior</a> page.
+
+<auro-header level="2" id="ariaRolesAndAttributes">ARIA Roles and Attributes</auro-header>
+<auro-header level="3" id="trigger">Trigger</auro-header>
+The trigger element exposes the following ARIA attributes:
+
+| Attribute | Value | Description |
+|---|---|---|
+| `role` | `combobox` | Identifies the trigger as a combobox control. |
+| `aria-expanded` | `true` / `false` | Reflects whether the bib (listbox) is currently open. |
+| `aria-controls` | `{bib-id}` | References the bib element that the trigger controls. |
+| `aria-labelledby` | `{label-id}` | Associates the trigger with its visible label text. |
+| `aria-activedescendant` | `{option-id}` | Points to the currently highlighted option when the bib is open. Cleared when the bib closes. |
+
+<auro-header level="3" id="menuOptions">Menu Options</auro-header>
+Each menu option exposes the following ARIA attributes:
+
+| Attribute | Value | Description |
+|---|---|---|
+| `role` | `option` | Identifies each item as a selectable option. |
+| `aria-selected` | `true` / `false` | Indicates whether the option is currently selected. |
+| `aria-setsize` | `{count}` | Total number of options available, so screen readers can announce "option X of Y." |
+| `aria-posinset` | `{index}` | The 1-based position of the option within the set. |
+
+<auro-header level="3" id="helpTextAndErrors">Help Text and Errors</auro-header>
+- Help text is associated with the component so screen readers can announce contextual guidance.
+- When validation fails, the error message is rendered with `role="alert"` and `aria-live="assertive"` to ensure it is announced immediately.
+
+<auro-header level="2" id="activeDescendant">Active Descendant</auro-header>
+Focus management in `auro-select` follows the **active descendant** pattern rather than moving DOM focus between options:
+
+1. When the bib opens, focus remains on the **trigger** element.
+2. Arrow keys update `aria-activedescendant` on the trigger to reference the currently highlighted option.
+3. This allows screen readers to announce each option as the user navigates without moving focus away from the trigger.
+
+When the bib closes, `aria-activedescendant` is cleared so stale references are not announced.
+
+<auro-header level="2" id="screenReaderAnnouncements">Screen Reader Announcements</auro-header>
+The component uses a visually hidden live region (`aria-live="polite"`) to announce state changes:
+
+- **Option highlighted** — When an option becomes active (via arrow keys or type-ahead), the live region announces the option text along with its selected state (e.g. "Apples, not selected").
+- **Option selected** — After an option is selected, the live region announces the selected value (e.g. "Apples, selected"). This announcement is slightly delayed to avoid being overridden by the bib's collapse announcement.
+
+<auro-header level="2" id="accessibleLabels">Accessible Labels</auro-header>
+- The `label` slot content is used as the accessible name for both the trigger (via `aria-labelledby`) and the menu (via `aria-label`).
+- A label is required. Without it, assistive technology users will not have context for what the select controls.
+- The `(optional)` label is automatically appended when the `required` attribute is not set.
+
+<auro-header level="2" id="fullscreenBehavior">Fullscreen (Modal) Behavior</auro-header>
+On smaller viewports, the bib opens as a fullscreen modal dialog:
+
+- The dialog is opened with `showModal()`, which provides **native focus trapping** — only elements inside the dialog are reachable via Tab.
+- Content outside the dialog is automatically made **inert** by the browser, preventing interaction with the page behind it.
+- The dialog receives an accessible label derived from the component's `label` slot text via `aria-labelledby`.
+- A close button inside the dialog is focused when the modal opens, giving screen reader users an immediate action to dismiss it.
+- Touch scrolling on the page behind the dialog is blocked to prevent the background from scrolling into view.
+
+<auro-header level="2" id="reducedMotion">Reduced Motion</auro-header>
+The component respects the `prefers-reduced-motion` media query. When the user has requested reduced motion, scroll animations (e.g. scrolling the selected or active option into view) use instant scrolling instead of smooth scrolling.
+
+<auro-header level="2" id="formParticipation">Form Participation</auro-header>
+A hidden native `<select>` element is rendered alongside the custom component with `aria-hidden="true"`. This element:
+
+- Participates in HTML form submissions, ensuring the selected value is included in form data.
+- Supports the `required` and `disabled` attributes.
+- Is invisible and unreachable by assistive technology — all user interaction goes through the custom component.
+
+</div>
+</div>
+</div>