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

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

@@ -146,6 +146,7 @@ let AuroLibraryRuntimeUtils$1 = class AuroLibraryRuntimeUtils {
 // See LICENSE in the project root for license information.
 
 
+/* eslint-disable jsdoc/no-undefined-types -- @fires event names are not types */
 /**
  * The `auro-checkbox` element is for the purpose of allowing users to select one or more options of a limited number of choices.
  * @customElement auro-checkbox
@@ -156,9 +157,10 @@ let AuroLibraryRuntimeUtils$1 = class AuroLibraryRuntimeUtils {
  *
  * @slot default - The default slot for the checkbox label.
  *
- * @fires {CustomEvent<any>} change - (Deprecated) Notifies when checked value is changed.
- * @fires {InputEvent} input - Notifies when when checked value is changed by user's interface.
+ * @fires change - (Deprecated) Notifies when checked value is changed.
+ * @fires input - Notifies when when checked value is changed by user's interface.
  */
+/* eslint-enable jsdoc/no-undefined-types */
 
 // build the component class
 class AuroCheckbox extends i$2 {
@@ -1687,7 +1689,7 @@ class AuroHelpText extends i$2 {
   }
 }
 
-var formkitVersion = '202604222117';
+var formkitVersion = '202604232130';
 
 // Copyright (c) 2026 Alaska Airlines. All rights reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.

package/components/checkbox/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.
 -->
 
 # Checkbox
@@ -26,30 +26,28 @@ The `<auro-checkbox>` element should be used in situations where users may:
 ### Basic
 
 <div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/basic.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/basic.html -->
-  <auro-checkbox-group>
-    <span slot="legend">Form label goes here</span>
-    <auro-checkbox value="value1" name="basic" id="checkbox-basic1">Checkbox option</auro-checkbox>
-    <auro-checkbox value="value2" name="basic" id="checkbox-basic2" checked>Checkbox option</auro-checkbox>
-    <auro-checkbox value="value3" name="basic" id="checkbox-basic3">Checkbox option that has some extra text that should wrap when rendered in a narrow container</auro-checkbox>
-    <auro-checkbox value="value4" name="basic" id="checkbox-basic4">Checkbox option</auro-checkbox>
-  </auro-checkbox-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-checkbox-group>
+<span slot="legend">Form label goes here</span>
+<auro-checkbox value="value1" name="basic" id="checkbox-basic1">Checkbox option</auro-checkbox>
+<auro-checkbox value="value2" name="basic" id="checkbox-basic2" checked>Checkbox option</auro-checkbox>
+<auro-checkbox value="value3" name="basic" id="checkbox-basic3">Checkbox option that has some extra text that should wrap when rendered in a narrow container</auro-checkbox>
+<auro-checkbox value="value4" name="basic" id="checkbox-basic4">Checkbox option</auro-checkbox>
+</auro-checkbox-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-checkbox-group>
-  <span slot="legend">Form label goes here</span>
-  <auro-checkbox value="value1" name="basic" id="checkbox-basic1">Checkbox option</auro-checkbox>
-  <auro-checkbox value="value2" name="basic" id="checkbox-basic2" checked>Checkbox option</auro-checkbox>
-  <auro-checkbox value="value3" name="basic" id="checkbox-basic3">Checkbox option that has some extra text that should wrap when rendered in a narrow container</auro-checkbox>
-  <auro-checkbox value="value4" name="basic" id="checkbox-basic4">Checkbox option</auro-checkbox>
-</auro-checkbox-group>
-```
+<pre class="language-html"><code class="language-html">&lt;auro-checkbox-group&gt;
+  &lt;span slot="legend"&gt;Form label goes here&lt;/span&gt;
+  &lt;auro-checkbox value="value1" name="basic" id="checkbox-basic1"&gt;Checkbox option&lt;/auro-checkbox&gt;
+  &lt;auro-checkbox value="value2" name="basic" id="checkbox-basic2" checked&gt;Checkbox option&lt;/auro-checkbox&gt;
+  &lt;auro-checkbox value="value3" name="basic" id="checkbox-basic3"&gt;Checkbox option that has some extra text that should wrap when rendered in a narrow container&lt;/auro-checkbox&gt;
+  &lt;auro-checkbox value="value4" name="basic" id="checkbox-basic4"&gt;Checkbox option&lt;/auro-checkbox&gt;
+&lt;/auro-checkbox-group&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>

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

@@ -138,6 +138,7 @@ let AuroLibraryRuntimeUtils$1 = class AuroLibraryRuntimeUtils {
 // See LICENSE in the project root for license information.
 
 
+/* eslint-disable jsdoc/no-undefined-types -- @fires event names are not types */
 /**
  * The `auro-checkbox` element is for the purpose of allowing users to select one or more options of a limited number of choices.
  * @customElement auro-checkbox
@@ -148,9 +149,10 @@ let AuroLibraryRuntimeUtils$1 = class AuroLibraryRuntimeUtils {
  *
  * @slot default - The default slot for the checkbox label.
  *
- * @fires {CustomEvent<any>} change - (Deprecated) Notifies when checked value is changed.
- * @fires {InputEvent} input - Notifies when when checked value is changed by user's interface.
+ * @fires change - (Deprecated) Notifies when checked value is changed.
+ * @fires input - Notifies when when checked value is changed by user's interface.
  */
+/* eslint-enable jsdoc/no-undefined-types */
 
 // build the component class
 class AuroCheckbox extends i$2 {
@@ -1679,7 +1681,7 @@ class AuroHelpText extends i$2 {
   }
 }
 
-var formkitVersion = '202604222117';
+var formkitVersion = '202604232130';
 
 // Copyright (c) 2026 Alaska Airlines. All rights reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.

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

@@ -0,0 +1,39 @@
+<auro-header level="1" id="overview">Checkbox - Keyboard Behavior</auro-header>
+<div class="contentWrapper">
+<div class="mainContent">
+<div class="scrollWrapper">
+<auro-header level="2" id="tabBehavior">Tab Behavior</auro-header>
+<p>Each <code>&lt;auro-checkbox&gt;</code> participates independently in the browser's default <code>tabindex</code> sequence. When a checkbox is <code>disabled</code> it is removed from the <code>tabindex</code> sequence.</p>
+<p>Arrow key navigation within a <code>&lt;auro-checkbox-group&gt;</code> is not currently supported.</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>Checkbox element</td>
+<td>
+Toggles the <code>checked</code> state. Calls <code>preventDefault()</code> to block page scroll.
+</td>
+</tr>
+</tbody>
+</table>
+<div class="note">
+<p><strong>Note:</strong> Arrow key navigation within a <code>&lt;auro-checkbox-group&gt;</code> is not currently supported. Each checkbox participates independently in the browser's default <code>tabindex</code> sequence.</p>
+</div>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+</div>
+</div>

package/components/checkbox/demo/readme.md

@@ -45,9 +45,7 @@ The `<auro-checkbox>` element should be used in situations where users may:
 
 #### 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 -->
@@ -56,13 +54,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 -->
@@ -73,9 +69,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-checkbox/+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-checkbox/+esm"&gt;&lt;/script&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 
 ## Formkit Development
@@ -89,9 +83,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 -->
@@ -106,37 +98,33 @@ 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 { AuroCheckbox, AuroCheckboxGroup } from '@aurodesignsystem/auro-formkit/auro-checkbox/class';
-
+​
 // Register with a custom name if desired
 AuroCheckbox.register('custom-checkbox');
-AuroCheckboxGroup.register('custom-checkbox-group');
-```
+AuroCheckboxGroup.register('custom-checkbox-group');</code></pre>
 
 This will create a new custom element `<custom-checkbox>` and `<custom-checkbox-group>` that behaves exactly like `<auro-checkbox>` and `<auro-checkbox-group>`, allowing both to coexist on the same page without interfering with each other.
 
 <div class="exampleWrapper exampleWrapper--flex">
-  <custom-checkbox-group>
-    <span slot="legend">Form label goes here</span>
-    <custom-checkbox value="value1" name="custom" id="checkbox-custom1">Custom checkbox option</custom-checkbox>
-    <custom-checkbox value="value2" name="custom" id="checkbox-custom2" checked>Custom checkbox option</custom-checkbox>
-    <custom-checkbox value="value3" name="custom" id="checkbox-custom3">Custom checkbox option</custom-checkbox>
-    <custom-checkbox value="value4" name="custom" id="checkbox-custom4">Custom checkbox option</custom-checkbox>
-  </custom-checkbox-group>
+<custom-checkbox-group>
+<span slot="legend">Form label goes here</span>
+<custom-checkbox value="value1" name="custom" id="checkbox-custom1">Custom checkbox option</custom-checkbox>
+<custom-checkbox value="value2" name="custom" id="checkbox-custom2" checked>Custom checkbox option</custom-checkbox>
+<custom-checkbox value="value3" name="custom" id="checkbox-custom3">Custom checkbox option</custom-checkbox>
+<custom-checkbox value="value4" name="custom" id="checkbox-custom4">Custom checkbox option</custom-checkbox>
+</custom-checkbox-group>
 </div>
 <auro-accordion alignRight>
-  <span slot="trigger">See code</span>
+<span slot="trigger">See code</span>
 
-```html
-  <custom-checkbox-group>
-    <span slot="legend">Form label goes here</span>
-    <custom-checkbox value="value1" name="custom" id="checkbox-custom1">Custom checkbox option</custom-checkbox>
-    <custom-checkbox value="value2" name="custom" id="checkbox-custom2" checked>Custom checkbox option</custom-checkbox>
-    <custom-checkbox value="value3" name="custom" id="checkbox-custom3">Custom checkbox option</custom-checkbox>
-    <custom-checkbox value="value4" name="custom" id="checkbox-custom4">Custom checkbox option</custom-checkbox>
-  </custom-checkbox-group>
-```
+<pre class="language-html"><code class="language-html">&lt;custom-checkbox-group&gt;
+  &lt;span slot="legend"&gt;Form label goes here&lt;/span&gt;
+  &lt;custom-checkbox value="value1" name="custom" id="checkbox-custom1"&gt;Custom checkbox option&lt;/custom-checkbox&gt;
+  &lt;custom-checkbox value="value2" name="custom" id="checkbox-custom2" checked&gt;Custom checkbox option&lt;/custom-checkbox&gt;
+  &lt;custom-checkbox value="value3" name="custom" id="checkbox-custom3"&gt;Custom checkbox option&lt;/custom-checkbox&gt;
+  &lt;custom-checkbox value="value4" name="custom" id="checkbox-custom4"&gt;Custom checkbox option&lt;/custom-checkbox&gt;
+&lt;/custom-checkbox-group&gt;</code></pre>
 </auro-accordion>
 <!-- AURO-GENERATED-CONTENT:END -->

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

@@ -8,8 +8,8 @@
  *
  * @slot default - The default slot for the checkbox label.
  *
- * @fires {CustomEvent<any>} change - (Deprecated) Notifies when checked value is changed.
- * @fires {InputEvent} input - Notifies when when checked value is changed by user's interface.
+ * @fires change - (Deprecated) Notifies when checked value is changed.
+ * @fires input - Notifies when when checked value is changed by user's interface.
  */
 export class AuroCheckbox extends LitElement {
     static get styles(): import("lit").CSSResult[];

package/components/checkbox/dist/index.js

@@ -98,6 +98,7 @@ let AuroLibraryRuntimeUtils$1 = class AuroLibraryRuntimeUtils {
 // See LICENSE in the project root for license information.
 
 
+/* eslint-disable jsdoc/no-undefined-types -- @fires event names are not types */
 /**
  * The `auro-checkbox` element is for the purpose of allowing users to select one or more options of a limited number of choices.
  * @customElement auro-checkbox
@@ -108,9 +109,10 @@ let AuroLibraryRuntimeUtils$1 = class AuroLibraryRuntimeUtils {
  *
  * @slot default - The default slot for the checkbox label.
  *
- * @fires {CustomEvent<any>} change - (Deprecated) Notifies when checked value is changed.
- * @fires {InputEvent} input - Notifies when when checked value is changed by user's interface.
+ * @fires change - (Deprecated) Notifies when checked value is changed.
+ * @fires input - Notifies when when checked value is changed by user's interface.
  */
+/* eslint-enable jsdoc/no-undefined-types */
 
 // build the component class
 class AuroCheckbox extends LitElement {
@@ -1632,7 +1634,7 @@ class AuroHelpText extends LitElement {
   }
 }
 
-var formkitVersion = '202604222117';
+var formkitVersion = '202604232130';
 
 // Copyright (c) 2026 Alaska Airlines. All rights reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.

package/components/checkbox/dist/registered.js

@@ -98,6 +98,7 @@ let AuroLibraryRuntimeUtils$1 = class AuroLibraryRuntimeUtils {
 // See LICENSE in the project root for license information.
 
 
+/* eslint-disable jsdoc/no-undefined-types -- @fires event names are not types */
 /**
  * The `auro-checkbox` element is for the purpose of allowing users to select one or more options of a limited number of choices.
  * @customElement auro-checkbox
@@ -108,9 +109,10 @@ let AuroLibraryRuntimeUtils$1 = class AuroLibraryRuntimeUtils {
  *
  * @slot default - The default slot for the checkbox label.
  *
- * @fires {CustomEvent<any>} change - (Deprecated) Notifies when checked value is changed.
- * @fires {InputEvent} input - Notifies when when checked value is changed by user's interface.
+ * @fires change - (Deprecated) Notifies when checked value is changed.
+ * @fires input - Notifies when when checked value is changed by user's interface.
  */
+/* eslint-enable jsdoc/no-undefined-types */
 
 // build the component class
 class AuroCheckbox extends LitElement {
@@ -1632,7 +1634,7 @@ class AuroHelpText extends LitElement {
   }
 }
 
-var formkitVersion = '202604222117';
+var formkitVersion = '202604232130';
 
 // Copyright (c) 2026 Alaska Airlines. All rights reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.

package/components/combobox/README.md

@@ -21,9 +21,19 @@ 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-combobox>` is the combination of [dropdown](http://auro.alaskaair.com/components/auro/dropdown), [input](http://auro.alaskaair.com/components/auro/input), and [menu](http://auro.alaskaair.com/components/auro/menu) and allows users to filter search results from a predefined list as they type. When the user starts typing in the text input, a dropdown of a menu shows up to display options that match the user’s search.
-
-By default, `auro-combobox` behaves as a suggestion list. This means any value may be typed into the combobox and the menu list presented effectively provides sample or suggestion options. With the use of the `persistInput` attribute the `auro-combobox` behaves as a filter of menu options. In this mode. typing into the input field will execute the filter but will not set the `value` of the combobox. The combobox value is set by selecting a menu option. Clicking the `X` clear button in the input will remove the current value of the HTML5 input causing the menu filter to reset as well as remove the current value of the combobox.
+<p><code>&lt;auro-combobox&gt;</code> combines a text input with a filterable dropdown menu, letting users either type a value or pick one from a list. As the user types, the menu narrows to show only matching options.</p>
+<p>The component supports two modes:</p>
+<ul>
+  <li><strong>Suggestion (default)</strong> — The user may type any value. The menu provides suggestions but does not restrict input.</li>
+  <li><strong>Filter</strong> — The user must select from the menu. Typing filters the available options but does not set the component's value. The value is only set when a menu option is selected.</li>
+</ul>
+<p>Common use cases:</p>
+<ul>
+  <li><strong>Airport or city search</strong> — Type a city name or airport code to filter a long list of destinations.</li>
+  <li><strong>Country or region selection</strong> — Quickly find and select from a large set of geographic options.</li>
+  <li><strong>Autocomplete fields</strong> — Provide type-ahead suggestions for form fields where the set of valid values is known.</li>
+  <li><strong>Search with suggestions</strong> — Offer recommended results while still allowing freeform input.</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/combobox/demo/accessibility.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/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-combobox | 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-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="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" />
+    <link rel="stylesheet" type="text/css" href="./styles.css" />
+  </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/combobox/demo/accessibility.md

@@ -0,0 +1,77 @@
+<auro-header level="1" id="overview">Combobox - Accessibility</auro-header>
+<div class="contentWrapper">
+<div class="mainContent">
+<div class="scrollWrapper">
+The `auro-combobox` component follows the <a href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/" target="_blank">W3C APG 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. |
+| `aria-autocomplete` | `list` / `both` | Indicates the type of autocomplete behavior provided by the combobox. |
+
+<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-combobox` follows the **active descendant** pattern rather than moving DOM focus between options:
+
+1. When the bib opens, focus remains on the **input** element.
+2. Arrow keys update `aria-activedescendant` on the input 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 input.
+
+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 input (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 combobox 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 `<input>` 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>

package/components/combobox/demo/api.html

@@ -33,6 +33,7 @@
     <!-- 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" />
+    <link rel="stylesheet" type="text/css" href="./styles.css" />
 </head>
   <body class="auro-markdown">
     <main></main>
@@ -46,7 +47,30 @@
           const rawHtml = marked.parse(text);
           document.querySelector('main').innerHTML = rawHtml;
           Prism.highlightAll();
+          addCopyButtons();
         });
+
+      function addCopyButtons() {
+        document.querySelectorAll('auro-accordion pre[class*="language-"]').forEach((pre) => {
+          const wrapper = document.createElement('div');
+          wrapper.className = 'pre-wrapper';
+          pre.parentNode.insertBefore(wrapper, pre);
+          wrapper.appendChild(pre);
+          const btn = document.createElement('button');
+          btn.className = 'copy-btn';
+          btn.textContent = 'Copy';
+          btn.addEventListener('click', () => {
+            const code = pre.querySelector('code');
+            const raw = code ? code.textContent : pre.textContent;
+            const text = raw.replace(/\u200B/g, '').replace(/^\n+/, '').replace(/\n+$/, '\n');
+            navigator.clipboard.writeText(text).then(() => {
+              btn.textContent = 'Copied!';
+              setTimeout(() => { btn.textContent = 'Copy'; }, 1500);
+            });
+          });
+          wrapper.appendChild(btn);
+        });
+      }
     </script>
 
     <!-- If additional elements are needed for the demo, add them here. -->