feat(dialog): use native HTML dialog element

.changeset/loud-coins-shake.md

@@ -0,0 +1,21 @@
+---
+"@rhds/elements": minor
+---
+
+`<rh-dialog>`: Dialog now uses the native HTML `<dialog>` element internally.
+
+Note: the `overlay` CSS shadow part is now deprecated in favor of the `--rh-dialog-backdrop-background-color` CSS custom property.  It will still work, but you can expect the `overlay` part to be removed in a future version
+
+Before:
+
+```css
+rh-dialog::part(overlay) { ... }
+```
+
+After:
+
+```css
+rh-dialog {
+  --rh-dialog-backdrop-background-color: ghostwhite;
+}
+```

elements/rh-dialog/demo/color-context.html

@@ -16,9 +16,7 @@ <h2 slot="header">Color Context</h2>
     <p>Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit. Donec sed
       odio dui. Maecenas faucibus mollis interdum. Fusce dapibus, tellus ac cursus commodo, tortor mauris
       condimentum nibh, ut fermentum massa justo sit amet risus.</p>
-    <rh-cta slot="footer">
-      <a href="#bar">Learn more</a>
-    </rh-cta>
+    <rh-cta slot="footer" href="#bar">Call to Action</rh-cta>
   </rh-dialog>
   <rh-button id="context-trigger">Open Dialog</rh-button>
 </rh-context-demo>

elements/rh-dialog/demo/events.html

@@ -6,9 +6,7 @@ <h2 slot="header">Modal dialog with a header</h2>
       aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
       fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit
       anim id est laborum.</p>
-    <rh-cta>
-      <a href="#bar">Learn more</a>
-    </rh-cta>
+    <rh-cta slot="footer" href="#bar">Call to Action</rh-cta>
   </rh-dialog>
   <rh-button id="trigger">Open</rh-button>
   <fieldset>

elements/rh-dialog/demo/lots-of-content.html

@@ -57,9 +57,7 @@ <h2 slot="header">Modal with a header with a truly excessive super duper long ti
   <p>Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit. Donec sed
     odio dui. Maecenas faucibus mollis interdum. Fusce dapibus, tellus ac cursus commodo, tortor mauris
     condimentum nibh, ut fermentum massa justo sit amet risus.</p>
-  <rh-cta slot="footer">
-    <a href="#bar">Learn more</a>
-  </rh-cta>
+  <rh-cta slot="footer" href="#bar">Call to Action</rh-cta>
 </rh-dialog>
 
 <script type="module">

elements/rh-dialog/demo/no-header-content.html

@@ -1,15 +1,13 @@
 <rh-button id="no-header-content-trigger">Open</rh-button>
 <rh-dialog trigger="no-header-content-trigger">
-  <p>A modal with no slotted header content</p>
-  <h3>This has no header content</h3>
+  <h2>This dialog has no slotted header content</h2>
+  <p>All this content exists in the default slot.</p>
   <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore
     magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
     consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
     pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est
     laborum.</p>
-  <rh-cta id="test-dark-child">
-    <a href="#">Call-to-action</a>
-  </rh-cta>
+  <rh-cta slot="footer" href="#bar">Call to Action</rh-cta>
 </rh-dialog>
 
 <script type="module">

elements/rh-dialog/demo/no-headings.html

@@ -1,13 +1,12 @@
 <rh-button id="no-headings-trigger">Open</rh-button>
-<rh-dialog trigger="no-headings-trigger">
-  <p>This modal doesn't have any headings. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
-    tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
-    laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
-    cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui
-    officia deserunt mollit anim id est laborum.</p>
-  <rh-cta>
-    <a href="#">Call-to-action</a>
-  </rh-cta>
+<rh-dialog accessible-label="This dialog's accessible name" trigger="no-headings-trigger">
+  <p>This dialog uses the <code>accessible-label</code> attribute to define its accessible name for assistive technology.
+     If the dialog includes a heading, the heading automatically becomes its accessible name—as long as the
+     <code>accessible-label</code> attribute does not exist. If neither a heading nor the <code>accessible-label</code>
+     attribute are provided, the dialog's accessible name defaults to the text content of its trigger element.
+     Learn more about these attributes in the <a href="https://ux.redhat.com/elements/dialog/code/">rh-dialog docs</a>.
+  </p>
+  <rh-cta slot="footer" href="#">Call to Action</rh-cta>
 </rh-dialog>
 
 <script type="module">

elements/rh-dialog/demo/rh-dialog.html

@@ -6,9 +6,7 @@ <h2 slot="header">Modal dialog with a header</h2>
     aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
     fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit
     anim id est laborum.</p>
-  <rh-cta>
-    <a href="#bar">Learn more</a>
-  </rh-cta>
+  <rh-cta slot="footer" href="#bar">Call to Action</rh-cta>
 </rh-dialog>
 
 <script type="module">

elements/rh-dialog/docs/40-accessibility.md

@@ -37,17 +37,22 @@ A dialog can be opened by pressing `Enter` when the dialog trigger has focus. Wh
 
 ## Focus order
 
+When a dialog opens, the close dialog button receives focus by default. Users have the ability to tab through each focusable element in the dialog. Depending on the browser, reaching the last focusable element may either:
+
+  1. Loop focus back to the close button
+  1. Move to focusable elements within the browser’s chrome
+
+While the dialog is open, interactive elements on the underlying page cannot be focused.
+
+### Changing focus order depending on content
+
 When a dialog opens, the element that should receive focus depends on the content and size of the modal. To help you decide where to place focus, follow these guidelines:
 
-- If the dialog contains semantic elements like lists or tables that are necessary to perceive in order to better understand dialog content, place focus on a static element at the start of the content
-  - The element that receives focus in this way must have `tabindex=“-1”`
 - If the dialog includes an irreversible action like deleting data, place focus on the least destructive action
 - If the dialog includes actions that simply provide additional information like `OK` or `Continue` buttons, place focus on the action that is likely to be most frequently used
-- If none of the above apply, place focus on the first focusable element
-- If placing focus on an element causes the beginning of dialog content to scroll out of view, place focus on a static element at the top instead
-  - The element that receives focus in this way must have `tabindex=“-1”`
-
+- If none of the above apply, focus is automatically placed on the close dialog button
 
+To move focus away from the close dialog button, listen for the [`open` event](https://ux.redhat.com/elements/dialog/code/#rh-dialog-apis) and move focus to the appropriate element in the lightdom via the [`focus()` method](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus).
 
 ## Touch targets
 
@@ -63,8 +68,22 @@ Only the close button and any interactive elements are selectable.
 
 ### Backdrop
 
-A dialog will not close by users clicking or tapping the backdrop or outside of the container.
+A dialog will close by users clicking or tapping the backdrop or outside of the container.
+
+
+## Accessible labels
+
+Each dialog needs an accessible name. If a dialog has a heading tag in the `header` or default slot, it will automatically be used as the accessible name of the dialog.
+
+If there is no slotted heading, users should provide an `accessible-label` attribute, the value of which will be used as the accessible name:
+
+```html
+<rh-dialog accessible-label="Page Properties" trigger="first-modal-trigger">
+  ...
+</rh-dialog>
+```
 
+If neither an `accessible-label` nor any headings exist, the accessible name of the dialog will fall back to the text of the dialog's trigger.
 
 
 ## Additional guidelines