@aurodesignsystem/auro-dialog 4.2.0 → 4.2.2-rc-1638600.1

package/CHANGELOG.md

@@ -1,26 +1,9 @@
-# [4.2.0](https://github.com/AlaskaAirlines/auro-dialog/compare/v4.1.1...v4.2.0) (2026-05-13)
+## [4.2.2-rc-1638600.1](https://github.com/AlaskaAirlines/auro-dialog/compare/v4.2.1...v4.2.2-rc-1638600.1) (2026-10-06)
 
 
 ### Bug Fixes
 
-* code cleanup as per review ([c9b967d](https://github.com/AlaskaAirlines/auro-dialog/commit/c9b967d45477a11757d39dab77be8c669bc26ca8))
-* lock page scroll for mobile screen ([3e55a6c](https://github.com/AlaskaAirlines/auro-dialog/commit/3e55a6c11f033f1d7decf494e9b944cc2cb04daa))
-* not to close dialog with backdrop click while another floatingUI open AB[#1536579](https://github.com/AlaskaAirlines/auro-dialog/issues/1536579) ([ab2c56b](https://github.com/AlaskaAirlines/auro-dialog/commit/ab2c56ba87fcb1c15f1ac5a6929316035c2f829e))
-* reset scroll lock on disconnectedCallback ([e12bd72](https://github.com/AlaskaAirlines/auro-dialog/commit/e12bd72083d3a7f5b2217b22052c31adbf8e7bc4))
-* restructure to work with floatingUI ([aa06280](https://github.com/AlaskaAirlines/auro-dialog/commit/aa06280a049dc084b6b89f3d75f4dbd99d9e8cff))
-
-
-### Features
-
-* integrate FloatingUI, native dialog/popover specs, and ::backdrop ([9a8b2c8](https://github.com/AlaskaAirlines/auro-dialog/commit/9a8b2c83724bcecab815f14668b0ce53858d6d8c))
-
-
-### Performance Improvements
-
-* bind open to isPopoverVisible ([316b5c6](https://github.com/AlaskaAirlines/auro-dialog/commit/316b5c6cd5173939e1e78fc21e3daa26751b8382))
-* bump engine to be `>=22` ([b71cc31](https://github.com/AlaskaAirlines/auro-dialog/commit/b71cc31168d5803683693799ded109f4aa0477d0))
-* remove scroll lock as floatingUI handles lock ([aeb1992](https://github.com/AlaskaAirlines/auro-dialog/commit/aeb19929bf639c2ddd4a41a9af1e015a1059f9d7))
-* update dependencies ([f138124](https://github.com/AlaskaAirlines/auro-dialog/commit/f13812417a258da0ce35e016966ba27f087f9437))
+* restore page scroll lock behind non-modal dialogs AB[#1625424](https://github.com/AlaskaAirlines/auro-dialog/issues/1625424) ([56c2f89](https://github.com/AlaskaAirlines/auro-dialog/commit/56c2f8944b170043f95509a97ec6bb9f5276706f)), closes [AB#1647843](https://github.com/AB/issues/1647843)
 
 # Semantic Release Automated Changelog
 

package/README.md

@@ -21,11 +21,9 @@ 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 -->
-The `<auro-dialog>` component is an intrusive interactive component, not passive. The component is best used when there is a requirement the user be made aware of the content being shown, moving focus from the main content to the dialog content.
-
-The component also supports a modal (blocking) state where the user must interact with the content of the component in order to continue. Passive dismissal of the content is not allowed. Users of this state must add a trigger for the user to move beyond this content.
-
-Auro holds the opinions of the [Nielsen Norman Group](https://www.nngroup.com/articles/modal-nonmodal-dialog/) on dialog and modal use to be true.
+<p>The <code>&lt;auro-dialog&gt;</code> component is an intrusive interactive component, not passive. The component is best used when there is a requirement the user be made aware of the content being shown, moving focus from the main content to the dialog content.</p>
+<p>The component also supports a modal (blocking) state where the user must interact with the content of the component in order to continue. Passive dismissal of the content is not allowed. Users of this state must add a trigger for the user to move beyond this content.</p>
+<p>Auro holds the opinions of the <a class="hyperlink" href="https://www.nngroup.com/articles/modal-nonmodal-dialog/" target="_blank">Nielsen Norman Group</a> on dialog and modal use to be true.</p>
 <!-- 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 -->
@@ -35,10 +33,11 @@ Auro holds the opinions of the [Nielsen Norman Group](https://www.nngroup.com/ar
 
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/useCases.md) -->
 <!-- The below content is automatically added from ./docs/partials/useCases.md -->
-The `<auro-dialog>` component should be used in situations where users may:
-
-* Be prompted to take an action before doing anything else or going back
-* Be prompted to view content with the option of closing it
+<p>The <code>&lt;auro-dialog&gt;</code> component should be used in situations where users may:</p>
+<ul>
+<li>Be prompted to take an action before doing anything else or going back</li>
+<li>Be prompted to view content with the option of closing it</li>
+</ul>
 <!-- AURO-GENERATED-CONTENT:END -->
 
 ## Install
@@ -49,9 +48,7 @@ The `<auro-dialog>` component should be used in situations where users may:
 [![License](https://img.shields.io/npm/l/@aurodesignsystem/auro-dialog?color=blue&style=for-the-badge)](https://www.apache.org/licenses/LICENSE-2.0)
 ![ESM supported](https://img.shields.io/badge/ESM-compatible-FFE900?style=for-the-badge)
 
-```shell
-$ npm i @aurodesignsystem/auro-dialog
-```
+<pre class="language-shell"><code class="language-shell">$ npm i @aurodesignsystem/auro-dialog</code></pre>
 
 <!-- AURO-GENERATED-CONTENT:END -->
 
@@ -63,9 +60,7 @@ Defining the dependency within each project that is using the `<auro-dialog>` co
 <!-- AURO-GENERATED-CONTENT:END -->
 <!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/auro-templates/main/templates/default/partials/usage/componentImport.md) -->
 
-```js
-import "@aurodesignsystem/auro-dialog";
-```
+<pre class="language-js"><code class="language-js">import "@aurodesignsystem/auro-dialog";</code></pre>
 
 <!-- AURO-GENERATED-CONTENT:END -->
 
@@ -74,9 +69,7 @@ import "@aurodesignsystem/auro-dialog";
 <!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/auro-templates/main/templates/default/partials/usage/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-dialog@latest/+esm"></script>
-```
+<pre class="language-html"><code class="language-html">&lt;script type="module" src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-dialog@latest/+esm"&gt;&lt;/script&gt;</code></pre>
 
 <!-- AURO-GENERATED-CONTENT:END -->
 
@@ -85,28 +78,26 @@ In cases where the project is not able to process JS assets, there are pre-proce
 <!-- AURO-GENERATED-CONTENT:START (CODE:src=./apiExamples/basic.html) -->
 <!-- The below code snippet is automatically added from ./apiExamples/basic.html -->
 
-```html
-<div>
-  <auro-button id="openBasic">Open default dialog</auro-button>
-</div>
-<auro-dialog id="defaultDialog">
-  <span slot="header">Default Dialog</span>
-  <div slot="content">
-    <p>When traveling on Alaska Airlines flights, Alaska Airlines checked baggage fees may apply. See <auro-hyperlink href="https://www.alaskaair.com/bagrules" target="_blank">alaskaair.com/bagrules</auro-hyperlink> for our rules. For itineraries that include other airlines, their checked baggage fees may apply, as displayed on their websites.</p>
-    <p>Baggage rules and fees will be based on the specific itinerary chosen. The applicable first and second bag fees will be displayed after you have added flights to the cart.</p>
-    <auro-header level="3" display="500">Before checking your bags, remember to:</auro-header>
-    <ul>
-      <li>Caerphilly croque monsieur fondue</li>
-      <li>Taleggio goat mascarpone cow manchego cheese and wine emmental cheese strings</li>
-      <li>Cheddar cheese and biscuits chalk and cheese</li>
-      <li>Camembert de normandie stinking bishop bavarian bergkase</li>
-    </ul>
-  </div>
-  <div slot="footer">
-    <auro-button secondary id="closeBasic">Close</auro-button>
-  </div>
-</auro-dialog>
-```
+<pre class="language-html"><code class="language-html">&lt;div&gt;
+  &lt;auro-button id="openBasic"&gt;Open default dialog&lt;/auro-button&gt;
+&lt;/div&gt;
+&lt;auro-dialog id="defaultDialog"&gt;
+  &lt;span slot="header"&gt;Default Dialog&lt;/span&gt;
+  &lt;div slot="content"&gt;
+    &lt;p&gt;When traveling on Alaska Airlines flights, Alaska Airlines checked baggage fees may apply. See &lt;auro-hyperlink href="https://www.alaskaair.com/bagrules" target="_blank"&gt;alaskaair.com/bagrules&lt;/auro-hyperlink&gt; for our rules. For itineraries that include other airlines, their checked baggage fees may apply, as displayed on their websites.&lt;/p&gt;
+    &lt;p&gt;Baggage rules and fees will be based on the specific itinerary chosen. The applicable first and second bag fees will be displayed after you have added flights to the cart.&lt;/p&gt;
+    &lt;auro-header level="3" display="500"&gt;Before checking your bags, remember to:&lt;/auro-header&gt;
+    &lt;ul&gt;
+      &lt;li&gt;Caerphilly croque monsieur fondue&lt;/li&gt;
+      &lt;li&gt;Taleggio goat mascarpone cow manchego cheese and wine emmental cheese strings&lt;/li&gt;
+      &lt;li&gt;Cheddar cheese and biscuits chalk and cheese&lt;/li&gt;
+      &lt;li&gt;Camembert de normandie stinking bishop bavarian bergkase&lt;/li&gt;
+    &lt;/ul&gt;
+  &lt;/div&gt;
+  &lt;div slot="footer"&gt;
+    &lt;auro-button secondary id="closeBasic"&gt;Close&lt;/auro-button&gt;
+  &lt;/div&gt;
+&lt;/auro-dialog&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 
 ## Custom Component Registration for Version Management
@@ -123,67 +114,63 @@ You can do this by importing only the component class and using the `register(na
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/customRegistration.md) -->
 <!-- The below content is automatically added from ./docs/partials/customRegistration.md -->
 
-```js
-// Import the class only
+<pre class="language-js"><code class="language-js">// Import the class only
 import { AuroDialog } from '@aurodesignsystem/auro-dialog/class';
-
+​
 // Register with a custom name if desired
-AuroDialog.register('custom-dialog');
-```
+AuroDialog.register('custom-dialog');</code></pre>
 
 This will create a new custom element `<custom-dialog>` that behaves exactly like `<auro-dialog>`, allowing both to coexist on the same page without interfering with each other.
 <!-- AURO-GENERATED-CONTENT:END -->
 <div class="exampleWrapper exampleWrapper--flex">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./apiExamples/custom.html) -->
-  <!-- The below content is automatically added from ./apiExamples/custom.html -->
-  <div>
-    <auro-button id="openCustom">Open default dialog</auro-button>
-  </div>
-  <custom-dialog id="customDialog">
-    <span slot="header">Default Dialog</span>
-    <div slot="content">
-      <p>When traveling on Alaska Airlines flights, Alaska Airlines checked baggage fees may apply. See <auro-hyperlink href="https://www.alaskaair.com/bagrules" target="_blank">alaskaair.com/bagrules</auro-hyperlink> for our rules. For itineraries that include other airlines, their checked baggage fees may apply, as displayed on their websites.</p>
-      <p>Baggage rules and fees will be based on the specific itinerary chosen. The applicable first and second bag fees will be displayed after you have added flights to the cart.</p>
-      <auro-header level="3" display="500">Before checking your bags, remember to:</auro-header>
-      <ul>
-        <li>Caerphilly croque monsieur fondue</li>
-        <li>Taleggio goat mascarpone cow manchego cheese and wine emmental cheese strings</li>
-        <li>Cheddar cheese and biscuits chalk and cheese</li>
-        <li>Camembert de normandie stinking bishop bavarian bergkase</li>
-      </ul>
-    </div>
-    <div slot="footer">
-      <auro-button secondary id="closeCustom">Close</auro-button>
-    </div>
-  </custom-dialog>
-  <!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./apiExamples/custom.html) -->
+<!-- The below content is automatically added from ./apiExamples/custom.html -->
+<div>
+<auro-button id="openCustom">Open default dialog</auro-button>
+</div>
+<custom-dialog id="customDialog">
+<span slot="header">Default Dialog</span>
+<div slot="content">
+<p>When traveling on Alaska Airlines flights, Alaska Airlines checked baggage fees may apply. See <auro-hyperlink href="https://www.alaskaair.com/bagrules" target="_blank">alaskaair.com/bagrules</auro-hyperlink> for our rules. For itineraries that include other airlines, their checked baggage fees may apply, as displayed on their websites.</p>
+<p>Baggage rules and fees will be based on the specific itinerary chosen. The applicable first and second bag fees will be displayed after you have added flights to the cart.</p>
+<auro-header level="3" display="500">Before checking your bags, remember to:</auro-header>
+<ul>
+<li>Caerphilly croque monsieur fondue</li>
+<li>Taleggio goat mascarpone cow manchego cheese and wine emmental cheese strings</li>
+<li>Cheddar cheese and biscuits chalk and cheese</li>
+<li>Camembert de normandie stinking bishop bavarian bergkase</li>
+</ul>
+</div>
+<div slot="footer">
+<auro-button secondary id="closeCustom">Close</auro-button>
+</div>
+</custom-dialog>
+<!-- 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/custom.html) -->
 <!-- The below code snippet is automatically added from ./apiExamples/custom.html -->
 
-```html
-<div>
-  <auro-button id="openCustom">Open default dialog</auro-button>
-</div>
-<custom-dialog id="customDialog">
-  <span slot="header">Default Dialog</span>
-  <div slot="content">
-    <p>When traveling on Alaska Airlines flights, Alaska Airlines checked baggage fees may apply. See <auro-hyperlink href="https://www.alaskaair.com/bagrules" target="_blank">alaskaair.com/bagrules</auro-hyperlink> for our rules. For itineraries that include other airlines, their checked baggage fees may apply, as displayed on their websites.</p>
-    <p>Baggage rules and fees will be based on the specific itinerary chosen. The applicable first and second bag fees will be displayed after you have added flights to the cart.</p>
-    <auro-header level="3" display="500">Before checking your bags, remember to:</auro-header>
-    <ul>
-      <li>Caerphilly croque monsieur fondue</li>
-      <li>Taleggio goat mascarpone cow manchego cheese and wine emmental cheese strings</li>
-      <li>Cheddar cheese and biscuits chalk and cheese</li>
-      <li>Camembert de normandie stinking bishop bavarian bergkase</li>
-    </ul>
-  </div>
-  <div slot="footer">
-    <auro-button secondary id="closeCustom">Close</auro-button>
-  </div>
-</custom-dialog>
-```
+<pre class="language-html"><code class="language-html">&lt;div&gt;
+  &lt;auro-button id="openCustom"&gt;Open default dialog&lt;/auro-button&gt;
+&lt;/div&gt;
+&lt;custom-dialog id="customDialog"&gt;
+  &lt;span slot="header"&gt;Default Dialog&lt;/span&gt;
+  &lt;div slot="content"&gt;
+    &lt;p&gt;When traveling on Alaska Airlines flights, Alaska Airlines checked baggage fees may apply. See &lt;auro-hyperlink href="https://www.alaskaair.com/bagrules" target="_blank"&gt;alaskaair.com/bagrules&lt;/auro-hyperlink&gt; for our rules. For itineraries that include other airlines, their checked baggage fees may apply, as displayed on their websites.&lt;/p&gt;
+    &lt;p&gt;Baggage rules and fees will be based on the specific itinerary chosen. The applicable first and second bag fees will be displayed after you have added flights to the cart.&lt;/p&gt;
+    &lt;auro-header level="3" display="500"&gt;Before checking your bags, remember to:&lt;/auro-header&gt;
+    &lt;ul&gt;
+      &lt;li&gt;Caerphilly croque monsieur fondue&lt;/li&gt;
+      &lt;li&gt;Taleggio goat mascarpone cow manchego cheese and wine emmental cheese strings&lt;/li&gt;
+      &lt;li&gt;Cheddar cheese and biscuits chalk and cheese&lt;/li&gt;
+      &lt;li&gt;Camembert de normandie stinking bishop bavarian bergkase&lt;/li&gt;
+    &lt;/ul&gt;
+  &lt;/div&gt;
+  &lt;div slot="footer"&gt;
+    &lt;auro-button secondary id="closeCustom"&gt;Close&lt;/auro-button&gt;
+  &lt;/div&gt;
+&lt;/custom-dialog&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>

package/demo/accessibility.html

@@ -0,0 +1,42 @@
+<!--
+  Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
+  See LICENSE in the project root for license information.
+
+  Demo shell. Content authored in ../docs/pages/accessibility.md → ./accessibility.md.
+  Rendered by ./demo-support.js (remark/rehype) with the top page-nav from ./pages.json.
+-->
+<!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-dialog | Accessibility</title>
+
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.9.0/build/styles/github.min.css"/>
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/legacy/auro-classic/CSSCustomProperties.css"/>
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/themes/alaska/CSSCustomProperties--alaska.min.css"/>
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/bundled/themes/alaska.global.min.css" />
+    <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="./demo-nav.css" />
+  </head>
+  <body class="auro-markdown">
+    <main></main>
+
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-accordion@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-nav@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-header@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-icon@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-hyperlink@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-button@latest/+esm" type="module"></script>
+
+    <script type="module">
+      import { renderPage } from './support/demo-support.js';
+      await renderPage('./accessibility.md');
+    </script>
+    <script type="module" data-demo-script="true">
+      import { initExamples } from './accessibility.min.js';
+      initExamples();
+    </script>
+  </body>
+</html>

package/demo/accessibility.js

@@ -0,0 +1,21 @@
+import { initAccessibilityUnformattedHeaderExample } from "../apiExamples/accessibility-unformatted-header";
+import { initAriaLabelSlotExample } from "../apiExamples/aria-label";
+
+import "../src/registered";
+
+export function initExamples(initCount) {
+  // biome-ignore lint/style/noParameterAssign: legacy error handling
+  initCount = initCount || 0;
+
+  try {
+    initAccessibilityUnformattedHeaderExample();
+    initAriaLabelSlotExample();
+  } catch (_err) {
+    if (initCount <= 20) {
+      // setTimeout handles issue where content is sometimes loaded after the functions get called
+      setTimeout(() => {
+        initExamples(initCount + 1);
+      }, 100);
+    }
+  }
+}

package/demo/accessibility.md

@@ -0,0 +1,134 @@
+<auro-header level="1" id="overview">Dialog - Accessibility</auro-header>
+<div class="contentWrapper">
+<nav>
+<auro-nav anchorNavContent=".scrollWrapper">
+<span slot="mobileToggleCollapsed">View More</span>
+<span slot="mobileToggleExpanded">View Less</span>
+<auro-anchorlink fluid href="#semantics">Semantics &amp; Roles</auro-anchorlink>
+<auro-anchorlink fluid href="#labelling">Labelling</auro-anchorlink>
+<auro-anchorlink fluid href="#focusManagement">Focus Management</auro-anchorlink>
+<auro-anchorlink fluid href="#backgroundScroll">Background Scroll</auro-anchorlink>
+<auro-anchorlink fluid href="#unformattedA11y">Unformatted Dialogs</auro-anchorlink>
+<auro-anchorlink fluid href="#closeButtonLabel">Close Button Label</auro-anchorlink>
+</auro-nav>
+</nav>
+<div class="mainContent">
+<div class="scrollWrapper">
+<auro-header level="2" id="semantics">Semantics &amp; Roles</auro-header>
+<p>The component renders its content inside a native HTML <code>&lt;dialog&gt;</code> element, which carries the implicit <code>role="dialog"</code> and the built-in semantics that assistive technology expects.</p>
+<ul>
+<li>A <strong>non-modal</strong> dialog is presented using the Popover API. Focus is trapped inside it and the page behind it is frozen while it is open, so it is exposed to assistive technology as <code>aria-modal="true"</code>.</li>
+<li>A <strong>modal</strong> dialog is opened with <code>showModal()</code>, which does all of the above and additionally makes the rest of the page <code>inert</code> — content outside the dialog cannot be focused or interacted with until the dialog closes.</li>
+</ul>
+<auro-header level="2" id="labelling">Labelling</auro-header>
+<p>The dialog wires up two ARIA relationships automatically:</p>
+<table>
+<thead>
+<tr><th>Attribute</th><th>Points to</th><th>Purpose</th></tr>
+</thead>
+<tbody>
+<tr><td><code>aria-labelledby</code></td><td><code>#dialog-header</code></td><td>Gives the dialog its accessible name from the header content.</td></tr>
+<tr><td><code>aria-describedby</code></td><td><code>#dialog-content</code></td><td>Associates the body content as the dialog's description.</td></tr>
+</tbody>
+</table>
+<p>In a formatted dialog, the <code>header</code> slot is rendered inside the <code>#dialog-header</code> heading for you, so simply providing header content yields a correctly labelled dialog.</p>
+<auro-header level="2" id="focusManagement">Focus Management</auro-header>
+<p>The component manages focus across the full open/close lifecycle:</p>
+<ul>
+<li><strong>On open</strong> — once the open animation completes, focus is moved to the first focusable element inside the dialog.</li>
+<li><strong>While open</strong> — focus is trapped within the dialog. <code>Tab</code> and <code>Shift</code> + <code>Tab</code> cycle through the dialog's focusable elements and wrap at the ends; elements outside the dialog are not reachable.</li>
+<li><strong>On close</strong> — focus is restored to the element that was active (<code>document.activeElement</code>) when the dialog opened. The <code>triggerElement</code> property sets a fallback focus target, used only when no element was active at open time.</li>
+<li><strong>Dismissing with the keyboard</strong> — <code>Escape</code> closes a <strong>non-modal</strong> dialog. A <strong>modal</strong> dialog deliberately ignores <code>Escape</code> and must be dismissed through an explicit action, such as the close button. A non-modal dialog can also be dismissed by clicking the page behind it, but that affordance is not exposed to assistive technology while <code>aria-modal="true"</code> is set, so <code>Escape</code> is the equivalent path for keyboard and screen reader users.</li>
+</ul>
+<auro-header level="2" id="backgroundScroll">Background Scroll</auro-header>
+<p>Both presentations freeze the page behind the dialog for as long as it is open, and restore the previous scroll position when it closes. This is deliberate: content drifting out of view behind an open dialog is disorienting, and on touch devices and with a screen reader the page can otherwise move unexpectedly while someone is reading the dialog.</p>
+<p>The lock blocks every scroll vector — wheel, trackpad, touch, and the arrow and space keys — including the VoiceOver three-finger swipe, which <code>overflow: hidden</code> alone does not prevent. Content <em>inside</em> the dialog still scrolls normally.</p>
+<auro-header level="2" id="unformattedA11y">Unformatted Dialogs</auro-header>
+<p>An <code>unformatted</code> dialog does not render the default header heading, so the <code>aria-labelledby="dialog-header"</code> relationship has nothing to point at unless you supply it. To keep the dialog properly labelled, add <code>id="dialog-header"</code> to the heading element within your slotted content:</p>
+
+<pre class="language-html"><code class="language-html">&lt;auro-dialog unformatted&gt;
+  &lt;span slot="content"&gt;
+    &lt;h1 id="dialog-header" class="heading-lg"&gt;This is a header&lt;/h1&gt;
+    Custom, edge-to-edge content.
+  &lt;/span&gt;
+&lt;/auro-dialog&gt;</code></pre>
+
+<div class="exampleWrapper">
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/accessibility-unformatted-header.html) -->
+<!-- The below content is automatically added from ./../apiExamples/accessibility-unformatted-header.html -->
+<div>
+<auro-button id="openAccessibility">Unformatted Medium Dialog</auro-button>
+</div>
+<auro-dialog id="unformattedMdDialog" unformatted md lg close-button-appearance="inverse">
+<span slot="content">
+<img style="display: block; width: 100%" src="https://blog.alaskaair.com/wp-content/uploads/2020/11/111-psp-blog-img-guide.jpg" alt="alaska airlines pride lights" />
+<div class="unformattedWrapper">
+<h1 id="dialog-header" class="heading-lg">This is a header</h1>
+      These are words that are slotted into the scope of the custom element.
+</div>
+</span>
+</auro-dialog>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+<span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/accessibility-unformatted-header.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/accessibility-unformatted-header.html -->
+
+<pre class="language-html"><code class="language-html">&lt;div&gt;
+  &lt;auro-button id="openAccessibility"&gt;Unformatted Medium Dialog&lt;/auro-button&gt;
+&lt;/div&gt;
+&lt;auro-dialog id="unformattedMdDialog" unformatted md lg close-button-appearance="inverse"&gt;
+  &lt;span slot="content"&gt;
+    &lt;img style="display: block; width: 100%" src="https://blog.alaskaair.com/wp-content/uploads/2020/11/111-psp-blog-img-guide.jpg" alt="alaska airlines pride lights" /&gt;
+    &lt;div class="unformattedWrapper"&gt;
+      &lt;h1 id="dialog-header" class="heading-lg"&gt;This is a header&lt;/h1&gt;
+      These are words that are slotted into the scope of the custom element.
+    &lt;/div&gt;
+  &lt;/span&gt;
+&lt;/auro-dialog&gt;</code></pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+<auro-header level="2" id="closeButtonLabel">Close Button Label</auro-header>
+<p>The non-modal close button has an accessible label of <code>"Close"</code> by default. Provide the <code>ariaLabel.dialog.close</code> slot to override it — useful when the surrounding context calls for more specific wording.</p>
+<div class="exampleWrapper">
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/aria-label.html) -->
+<!-- The below content is automatically added from ./../apiExamples/aria-label.html -->
+<div>
+<auro-button id="openAriaLabelSlot">Unformatted Dialog w/ custom close button aria-label</auro-button>
+</div>
+<auro-dialog id="ariaLabelMdDialog" unformatted md lg ondark>
+<span slot="ariaLabel.dialog.close">This will be the new aria label for the close button</span>
+<span slot="content">
+<img style="display: block; width: 100%" src="https://blog.alaskaair.com/wp-content/uploads/2020/11/111-psp-blog-img-guide.jpg" alt="alaska airlines pride lights" />
+<div class="unformattedWrapper">
+<h1 id="dialog-header" class="heading-lg">This is a header</h1>
+      These are words that are slotted into the scope of the custom element.
+</div>
+</span>
+</auro-dialog>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+<span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/aria-label.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/aria-label.html -->
+
+<pre class="language-html"><code class="language-html">&lt;div&gt;
+  &lt;auro-button id="openAriaLabelSlot"&gt;Unformatted Dialog w/ custom close button aria-label&lt;/auro-button&gt;
+&lt;/div&gt;
+&lt;auro-dialog id="ariaLabelMdDialog" unformatted md lg ondark&gt;
+  &lt;span slot="ariaLabel.dialog.close"&gt;This will be the new aria label for the close button&lt;/span&gt;
+  &lt;span slot="content"&gt;
+    &lt;img style="display: block; width: 100%" src="https://blog.alaskaair.com/wp-content/uploads/2020/11/111-psp-blog-img-guide.jpg" alt="alaska airlines pride lights" /&gt;
+    &lt;div class="unformattedWrapper"&gt;
+      &lt;h1 id="dialog-header" class="heading-lg"&gt;This is a header&lt;/h1&gt;
+      These are words that are slotted into the scope of the custom element.
+    &lt;/div&gt;
+  &lt;/span&gt;
+&lt;/auro-dialog&gt;</code></pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+</div>
+</div>
+</div>