@aurodesignsystem/auro-dialog 4.2.0 → 4.2.1

package/demo/index.md

@@ -1,158 +1,234 @@
-<!--
- 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.
--->
-
-# Dialog
-
+<auro-header level="1" id="overview">Dialog - Overview and UX Guide</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="#description">Description</auro-anchorlink>
+<auro-anchorlink fluid href="#useCases">Use Cases</auro-anchorlink>
+<auro-anchorlink fluid href="#userStories">User Stories</auro-anchorlink>
+<auro-anchorlink fluid href="#modalExample">Modal</auro-anchorlink>
+</auro-nav>
+</nav>
+<div class="mainContent">
+<div class="scrollWrapper">
+<auro-header level="2" id="description">Description</auro-header>
 <!-- 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.
-<!-- AURO-GENERATED-CONTENT:END -->
-
-## Use Cases
-
-<!-- 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 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 -->
-
-## Set Up
-
-Triggering the dialog relies on functions being installed. See the following example code that is installed into this demo.
-
-```javascript
-function toggleDialog(dialogID) {
-  const dialog = document.querySelector(dialogID);
-
-  if (dialog.hasAttribute('open')) {
-    dialog.removeAttribute('open');
-  } else {
-    dialog.setAttribute('open', true);
-  }
-}
-```
-
-Once the JavaScript is added to the scope of the experience, the next part is adding a trigger. In this example, the button component will toggle a dialog with the ID of `#demo1`.
-
-```javascript
-<auro-button onClick="toggleDialog('#demo1')">Open Default Dialog</auro-button>
-```
-
-## The Structure
-
-The structure of the dialog itself consists of three slots. The `header`, `content` and `footer` slots. See the scaffolding example below for adding content to the component.
-
-```javascript
-  <auro-dialog id="[unique ID]">
-    <span slot="header">[header content]</span>
-    <span slot="content">
-      [body content]
-    </span>
-    <span slot="footer">
-      [footer content]
-    </span>
-  </auro-dialog>
-```
-
-It should be noted that the `footer` slot is reserved for the placement of action buttons.
-
-## Example(s)
-
-### Basic
-
-The dialog open state is controlled via the `open` attribute, or by programmatically setting the `open` property to `true`.
-You can see in the example below under the "See Code" section that we are controlling our dialogs by adding and removing the `open` attribute.
-
 <div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/basic.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/basic.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>
-  <!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/basic.html) -->
+<!-- The below content is automatically added from ./../apiExamples/basic.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>
+<!-- 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
+<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 -->
+</auro-accordion>
+<auro-header level="2" id="useCases">Use Cases</auro-header>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/useCases.md) -->
+<!-- The below content is automatically added from ./../docs/partials/useCases.md -->
+<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 -->
+<auro-header level="2" id="userStories">User Stories</auro-header>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/index/userStories.md) -->
+<!-- The below content is automatically added from ./../docs/partials/index/userStories.md -->
+<p>The following user stories describe the primary ways the <code>&lt;auro-dialog&gt;</code> component is intended to be used.</p>
+<auro-header level="3" id="story-dismissible">Dismissible dialog</auro-header>
+<p>As a user, I want to be shown important supplemental information in a focused overlay that I can dismiss — by pressing the close button, pressing <code>Esc</code>, or clicking outside the dialog — so I can return to the main content when I am done reading.</p>
+<auro-header level="3" id="story-modal">Modal (blocking) dialog</auro-header>
+<p>As a user, I need to be prompted to make a decision or acknowledge information before I can continue, so the experience presents a modal dialog that I must resolve with an explicit action before returning to the page.</p>
+<auro-header level="3" id="story-unformatted">Unformatted dialog</auro-header>
+<p>As a developer, I want the open/close behavior, focus management, and accessibility tooling of the dialog while supplying my own edge-to-edge layout, so I can present rich media or a fully custom composition inside the dialog window.</p>
+<!-- AURO-GENERATED-CONTENT:END -->
+<auro-header level="2" id="modalExample">Modal</auro-header>
+<p>The <code>modal</code> attribute locks the user into interacting with the dialog. The close icon is not rendered and clicking outside the dialog will not dismiss it, so a <code>modal</code> dialog must include an explicit action button in the footer to dismiss it.</p>
+<div class="exampleWrapper">
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/modal.html) -->
+<!-- The below content is automatically added from ./../apiExamples/modal.html -->
 <div>
-  <auro-button id="openBasic">Open default dialog</auro-button>
+<auro-button id="openDefaultModal">Open default modal</auro-button>
+<auro-button id="openMediumModal">Open medium modal</auro-button>
+<auro-button id="openSmallModal">Open small modal</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 id="defaultModalDialog" modal>
+<span slot="header">Default Modal 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 id="closeDefaultModal">I understand
+<auro-icon category="interface" name="chevron-right" emphasis appearance="inverse"></auro-icon>
+</auro-button>
+</div>
 </auro-dialog>
-```
-<!-- AURO-GENERATED-CONTENT:END -->
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/basic.js) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/basic.js -->
+<auro-dialog id="mediumModalDialog" md modal>
+<span slot="header">Medium 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 id="closeMediumModal">I understand
+<auro-icon category="interface" name="chevron-right" emphasis appearance="inverse"></auro-icon>
+</auro-button>
+</div>
+</auro-dialog>
+<auro-dialog id="smallModalDialog" sm modal>
+<span slot="header">Small 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 id="closeSmallModal">I understand
+<auro-icon category="interface" name="chevron-right" emphasis appearance="inverse"></auro-icon>
+</auro-button>
+</div>
+</auro-dialog>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+<span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/modal.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/modal.html -->
 
-```js
-export function initBasicExample() {
-  if (initBasicExample._initialized) {
-    return;
-  }
-  const buttons = [
-    document.querySelector("#openBasic"),
-    document.querySelector("#closeBasic"),
-  ];
-  const dialog = document.querySelector("#defaultDialog");
-  if (!buttons[0] || !buttons[1] || !dialog) {
-    return;
-  }
-  initBasicExample._initialized = true;
-
-  buttons.forEach((button) => {
-    button.addEventListener("click", () => {
-      if (dialog.hasAttribute("open")) {
-        dialog.removeAttribute("open");
-      } else {
-        dialog.setAttribute("open", true);
-      }
-    });
-  });
-}
-```
+<pre class="language-html"><code class="language-html">&lt;div&gt;
+  &lt;auro-button id="openDefaultModal"&gt;Open default modal&lt;/auro-button&gt;
+  &lt;auro-button id="openMediumModal"&gt;Open medium modal&lt;/auro-button&gt;
+  &lt;auro-button id="openSmallModal"&gt;Open small modal&lt;/auro-button&gt;
+&lt;/div&gt;
+&lt;auro-dialog id="defaultModalDialog" modal&gt;
+  &lt;span slot="header"&gt;Default Modal 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 id="closeDefaultModal"&gt;I understand
+      &lt;auro-icon category="interface" name="chevron-right" emphasis appearance="inverse"&gt;&lt;/auro-icon&gt;
+    &lt;/auro-button&gt;
+  &lt;/div&gt;
+&lt;/auro-dialog&gt;
+&lt;auro-dialog id="mediumModalDialog" md modal&gt;
+  &lt;span slot="header"&gt;Medium 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 id="closeMediumModal"&gt;I understand
+      &lt;auro-icon category="interface" name="chevron-right" emphasis appearance="inverse"&gt;&lt;/auro-icon&gt;
+    &lt;/auro-button&gt;
+  &lt;/div&gt;
+&lt;/auro-dialog&gt;
+&lt;auro-dialog id="smallModalDialog" sm modal&gt;
+  &lt;span slot="header"&gt;Small 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 id="closeSmallModal"&gt;I understand
+      &lt;auro-icon category="interface" name="chevron-right" emphasis appearance="inverse"&gt;&lt;/auro-icon&gt;
+    &lt;/auro-button&gt;
+  &lt;/div&gt;
+&lt;/auro-dialog&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
+</auro-accordion>
+</div>
+</div>
+</div>