@aurodesignsystem/auro-dialog 4.2.2 → 4.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/demo/voiceover.md CHANGED
@@ -1,6 +1,6 @@
1
- <auro-header level="1" id="overview">Dialog - VoiceOver Behavior</auro-header>
1
+ <auro-header level="1" id="overview">Dialog - VoiceOver behavior</auro-header>
2
2
  <p>This page documents the screen reader experience when using the <code>&lt;auro-dialog&gt;</code> component. Because the component is built on the native <code>&lt;dialog&gt;</code> element, announcements follow the platform's standard dialog conventions.</p>
3
- <auro-header level="2" id="openAnnouncement">Opening the Dialog</auro-header>
3
+ <auro-header level="2" id="openAnnouncement">Opening the dialog</auro-header>
4
4
  <p>When the dialog opens, focus is moved into it and the screen reader announces:</p>
5
5
  <ol>
6
6
  <li><strong>Role:</strong> <em>"dialog"</em> (from the native <code>&lt;dialog&gt;</code> element).</li>
@@ -8,12 +8,12 @@
8
8
  <li><strong>Description:</strong> the <code>content</code> slot, via <code>aria-describedby</code>.</li>
9
9
  <li><strong>First control:</strong> the first focusable element inside the dialog receives focus and is announced.</li>
10
10
  </ol>
11
- <auro-header level="2" id="navigatingContent">Navigating Content</auro-header>
12
- <p>Within the dialog, the user navigates with the standard reading and Tab commands. Focus is trapped, so swiping or tabbing past the last element wraps back to the first and never lands on the obscured page behind the dialog. For a modal dialog, the rest of the page is <code>inert</code>, so the screen reader's virtual cursor cannot reach it either.</p>
13
- <auro-header level="2" id="closeGesture">Closing the Dialog</auro-header>
11
+ <auro-header level="2" id="navigatingContent">Navigating content</auro-header>
12
+ <p>Within the dialog, the user navigates with the standard reading and Tab commands. Focus is trapped, so swiping or tabbing past the last element wraps back to the first and never lands on the obscured page behind the dialog. For a modal dialog, the rest of the page is <code>inert</code>, so the screen reader's virtual cursor can't reach it either.</p>
13
+ <auro-header level="2" id="closeGesture">Closing the dialog</auro-header>
14
14
  <ul>
15
- <li><strong>Non-modal:</strong> the dialog can be dismissed with the close button (announced using the <code>ariaLabel.dialog.close</code> slot text, or <em>"Close"</em> by default), the <code>Esc</code> key, or the platform dismiss gesture.</li>
16
- <li><strong>Modal:</strong> passive dismissal is disabled. The dismiss gesture and <code>Esc</code> have no effect — the user must activate the explicit action in the footer.</li>
15
+ <li><strong>Non-modal:</strong> the dialog can be dismissed with the close button (announced using the <code>ariaLabel.dialog.close</code> slot text, or <em>"Close"</em> by default) or the <code>Esc</code> key.</li>
16
+ <li><strong>Modal:</strong> passive dismissal is disabled. <code>Esc</code> has no effect, so the user must activate the explicit action in the footer.</li>
17
17
  </ul>
18
- <div class="note"><strong>iOS VoiceOver:</strong> the two-finger <em>"scrub"</em> (a <em>"Z"</em> shape) acts as the <code>Esc</code> key. <strong>Android TalkBack:</strong> the back gesture (swipe inward from a screen edge) dismisses a non-modal dialog.</div>
19
- <p>When the dialog closes, focus returns to the triggering element, so the screen reader resumes from where the user left off on the page.</p>
18
+ <div class="note"><strong>iOS VoiceOver:</strong> the two-finger <em>"scrub"</em> (a <em>"Z"</em> shape) doesn't currently close the dialog. Use the close button instead.</div>
19
+ <p>When the dialog closes, focus returns to the element that was active when the dialog opened, so the screen reader resumes from where the user left off on the page.</p>
@@ -1,20 +1,20 @@
1
1
  <auro-header level="1" id="overview">Dialog - Why auro-dialog?</auro-header>
2
2
  <p>The native HTML <code>&lt;dialog&gt;</code> element provides the foundation for overlays, but building a production-ready, accessible, on-brand dialog on top of it requires a substantial amount of repeated work. <code>&lt;auro-dialog&gt;</code> is built on the native element and layers on the behavior, styling, and accessibility that Alaska experiences need. This page explains what the component adds.</p>
3
3
  <auro-header level="2" id="modalControl">Unified modal and non-modal modes</auro-header>
4
- <p>Native <code>&lt;dialog&gt;</code> exposes two very different entry points — <code>show()</code> for non-modal and <code>showModal()</code> for modal — with different dismissal semantics you must wire up yourself.</p>
4
+ <p>Native <code>&lt;dialog&gt;</code> exposes two very different entry points: <code>show()</code> for non-modal and <code>showModal()</code> for modal. Each has different dismissal semantics that you must wire up yourself.</p>
5
5
  <p><code>&lt;auro-dialog&gt;</code> exposes a single <code>open</code> attribute plus a <code>modal</code> toggle, and handles the rest:</p>
6
6
  <ul>
7
7
  <li>Non-modal dialogs use the Popover API and dismiss on close button, <code>Esc</code>, or backdrop click.</li>
8
8
  <li>Modal dialogs use <code>showModal()</code>, suppress passive dismissal, and hide the close button so the user must take an explicit action.</li>
9
9
  </ul>
10
10
  <auro-header level="2" id="focusManagement">Focus management</auro-header>
11
- <p>With the native element you are responsible for moving focus into the dialog, trapping it, and restoring it afterward. <code>&lt;auro-dialog&gt;</code> does all three automatically: it focuses the first element on open, traps <code>Tab</code> focus while open, and restores focus to the triggering element (or a configurable <code>triggerElement</code>) on close.</p>
11
+ <p>With the native element, you're responsible for moving focus into the dialog, trapping it, and restoring it afterward. <code>&lt;auro-dialog&gt;</code> does all three automatically: it focuses the first element on open, traps <code>Tab</code> focus while open, and restores focus to the element that was active when the dialog opened, with <code>triggerElement</code> as a fallback.</p>
12
12
  <auro-header level="2" id="responsiveLayout">Responsive layout</auro-header>
13
- <p>Native dialogs have no built-in responsive behavior. <code>&lt;auro-dialog&gt;</code> adapts to the viewport — presenting as a full-width, size-scaled panel below the mobile breakpoint — and offers <code>sm</code>, <code>md</code>, and <code>lg</code> sizes that can be decoupled between desktop and mobile.</p>
14
- <auro-header level="2" id="theming">Styling &amp; theming</auro-header>
13
+ <p>Native dialogs have no built-in responsive behavior. <code>&lt;auro-dialog&gt;</code> adapts to the viewport, presenting as a full-width, size-scaled panel below the mobile breakpoint. It offers <code>sm</code>, <code>md</code>, and <code>lg</code> sizes that can be decoupled between desktop and mobile.</p>
14
+ <auro-header level="2" id="theming">Styling and theming</auro-header>
15
15
  <p>Styling a native <code>&lt;dialog&gt;</code> and its <code>::backdrop</code> from scratch is tedious and easy to get wrong. <code>&lt;auro-dialog&gt;</code> ships with Auro Design System styling out of the box, plus <code>::part()</code> selectors (<code>dialog</code>, <code>dialog-header</code>, <code>dialog-content</code>, <code>dialog-footer</code>, <code>close-button</code>) and design tokens for backdrop and surface colors.</p>
16
16
  <auro-header level="2" id="accessibility">Accessibility</auro-header>
17
- <p>The component wires up <code>aria-labelledby</code> and <code>aria-describedby</code> from the header and content slots, renders an accessible close button with a customizable label, and manages the <code>inert</code> background for modal dialogs — the details that are easy to omit when hand-rolling a dialog.</p>
17
+ <p>The component wires up <code>aria-labelledby</code> and <code>aria-describedby</code> from the header and content slots, renders an accessible close button with a customizable label, and manages the <code>inert</code> background for modal dialogs. These details are easy to omit when hand-rolling a dialog.</p>
18
18
  <auro-header level="2" id="layeredComponents">Layered components</auro-header>
19
19
  <p>Placing other floating UI (popovers, dropdowns) inside a native dialog can lead to top-layer stacking conflicts. <code>&lt;auro-dialog&gt;</code> coordinates with the shared Auro floating-UI runtime so layered components stack and dismiss correctly.</p>
20
20
  <auro-header level="2" id="summary">Summary</auro-header>
@@ -24,7 +24,7 @@
24
24
  </thead>
25
25
  <tbody>
26
26
  <tr><td>Modal / non-modal API</td><td>Two separate methods</td><td>Single <code>open</code> + <code>modal</code></td></tr>
27
- <tr><td>Focus trap &amp; restore</td><td>Manual</td><td>Automatic</td></tr>
27
+ <tr><td>Focus trap and restore</td><td>Manual</td><td>Automatic</td></tr>
28
28
  <tr><td>Responsive / mobile presentation</td><td>No</td><td>Automatic at breakpoint</td></tr>
29
29
  <tr><td>Size options</td><td>No</td><td><code>sm</code> / <code>md</code> / <code>lg</code>, decoupled by breakpoint</td></tr>
30
30
  <tr><td>Design system styling</td><td>Unstyled</td><td>On-brand, themeable</td></tr>