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: `#overlay` is now deprecated in favor of a public variable on the CSS psuedo-element `::backdrop`:
+
+Before:
+
+```css
+rh-dialog::part(overlay) { ... }
+```
+
+After:
+
+```css
+rh-dialog {
+  --rh-dialog-backdrop-background-color: ghostwhite;
+}
+```

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

@@ -1,7 +1,7 @@
 <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

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

@@ -1,11 +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>
+<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 <code>aria-label</code>.
+     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">
     <a href="#">Call-to-action</a>
   </rh-cta>
 </rh-dialog>

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

@@ -6,7 +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>
+  <rh-cta slot="footer">
     <a href="#bar">Learn more</a>
   </rh-cta>
 </rh-dialog>

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

@@ -37,17 +37,17 @@ 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 recieves focus by default. Users have the ability to tab through each focusable element in the dialog. When the last focusable element in the dialog is reached, focus returns to the close dialog button—effectively trapping focus inside the dialog.
+
+### 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 +63,24 @@ 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, this component will automatically apply an appropriate ID to the heading tag and an `aria-labelledby` attribute to the `<dialog>`.
+
+Users can optionally provide an `accessible-label` attribute which overrides the built-in `aria-labelledby` functionality:
+
+```html
+<rh-dialog accessible-label="Page Properties" trigger="first-modal-trigger">
+  ...
+</rh-dialog>
+```
+
+The `accessible-label` attribute assigns an `aria-label` to the `<dialog>` element.
 
+If neither an `accessible-label` nor any headings exist, the `aria-label` on the `<dialog>` will default to the text of the dialog's trigger.
 
 
 ## Additional guidelines