docs: add dialog docs

PiperOrigin-RevId: 555702496

docs/components/dialog.md

@@ -0,0 +1,240 @@
+<!-- catalog-only-start --><!-- ---
+name: Dialogs
+dirname: dialog
+-----><!-- catalog-only-end -->
+
+<catalog-component-header image-align="start">
+<catalog-component-header-title slot="title">
+
+# Dialogs
+
+<!--*
+# Document freshness: For more information, see go/fresh-source.
+freshness: { owner: 'lizmitchell' reviewed: '2023-08-08' }
+tag: 'docType:reference'
+*-->
+
+<!-- no-catalog-start -->
+
+<!-- go/md-dialog -->
+
+<!-- [TOC] -->
+
+<!-- external-only-start -->
+**This documentation is fully rendered on the
+[Material Web catalog](https://material-web.dev/components/dialog/)**
+<!-- external-only-end -->
+
+<!-- no-catalog-end -->
+
+[Dialogs](https://m3.material.io/components/dialogs)<!-- {.external} --> provide
+important prompts in a user flow.
+
+</catalog-component-header-title>
+
+<img class="hero" src="images/dialog/hero.png" alt="A dialog displaying phone ringtone options."
+title="A dialog">
+
+</catalog-component-header>
+
+*   [Design article](https://m3.material.io/components/dialogs) <!-- {.external} -->
+*   API Documentation (*coming soon*)
+*   [Source code](https://github.com/material-components/material-web/tree/main/dialog)
+    <!-- {.external} -->
+
+<!-- catalog-only-start -->
+
+<!--
+
+## Interactive Demo
+
+{% playgroundexample dirname=dirname %}
+
+-->
+
+<!-- catalog-only-end -->
+
+## Usage
+
+Dialogs behave like
+[`<dialog>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement)<!-- {.external} -->
+elements, and can be closed with a `<form method="dialog">` element.
+
+Dialogs have three optional sections: the headline title, the main content, and
+action buttons.
+
+```html
+<md-dialog>
+  <div slot="headline">
+    Dialog title
+  </div>
+  <form slot="content" id="form-id" method="dialog">
+    A simple dialog with free-form content.
+  </form>
+  <div slot="actions">
+    <md-text-button form="form-id">Ok</md-text-button>
+  </div>
+</md-dialog>
+```
+
+<!-- no-catalog-start -->
+<!-- TODO: add image -->
+<!-- no-catalog-end -->
+<!-- catalog-only-start -->
+
+<!--
+
+<div class="figure-wrapper">
+  <figure
+      style="justify-content:center;"
+      aria-label="">
+    TODO: update figure
+  </figure>
+</div>
+
+-->
+
+<!-- catalog-only-end -->
+
+> Tip: use `margin`, `height`, and `width` CSS properties to control the
+> dialog's size and position.
+
+### Opening and closing
+
+Dialogs are opened and closed by setting the `open` attribute or property.
+
+```html
+<md-dialog open>
+  <div slot="content">
+    A dialog that is opened by default.
+  </div>
+</md-dialog>
+```
+
+Dialogs are also opened and closed by calling `dialog.show()` and
+`dialog.close()`.
+
+Both return a Promise that resolves after the dialog's animation finishes.
+
+```ts
+closeButton.addEventListener('click', async () => {
+  await dialog.close();
+});
+```
+
+### Return value
+
+A button's value attribute will set the dialog's `returnValue` property to
+identify which button closed it.
+
+```html
+<md-dialog open>
+  <form slot="content" id="form-id" method="dialog">...</form>
+  <div slot="actions">
+    <md-text-button form="form-id" value="cancel">Cancel</md-text-button>
+    <md-text-button form="form-id" value="ok">Ok</md-text-button>
+  </div>
+</md-dialog>
+```
+
+```ts
+dialog.addEventListener('close', () => {
+  const cancelClicked = dialog.returnValue === 'cancel';
+  const okClicked = dialog.returnValue === 'ok';
+});
+```
+
+## Accessibility
+
+Dialogs are labelled by their headlines. Add an
+[`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label)<!-- {.external} -->
+attribute to dialogs without a headline.
+
+```html
+<md-dialog aria-label="Error message">
+  <div slot="content">An error occurred, details ...</div>
+</md-dialog>
+```
+
+### Alerts
+
+Add a
+[`type="alert"`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role)
+attribute to dialogs that need to communicate an important message and require a
+user's response.
+
+Common examples include error messages that require confirmation and other
+action confirmation prompts.
+
+```html
+<md-dialog type="alert">
+  <div slot="headline">Confirm deletion</div>
+  <form slot="content" id="form-id" method="dialog">
+    Are you sure you wish to delete this item?
+  </form>
+  <div slot="actions">
+    <md-text-button form="form-id" value="cancel">Cancel</md-text-button>
+    <md-text-button form="form-id" value="delete">Delete</md-text-button>
+  </div>
+</md-dialog>
+```
+
+## Theming
+
+Dialogs supports [Material theming](../theming.md) and can be customized in
+terms of color, typography, and shape.
+
+### Tokens
+
+Token                               | Default value
+----------------------------------- | ---------------------------------------
+`--md-dialog-container-color`       | `--md-sys-color-surface-container-high`
+`--md-dialog-headline-color`        | `--md-sys-color-on-surface`
+`--md-dialog-headline-type`         | `--md-sys-typescale-headline-small`
+`--md-dialog-supporting-text-color` | `--md-sys-color-on-surface-variant`
+`--md-dialog-supporting-text-type`  | `--md-sys-typescale-body-medium`
+
+*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-dialog.scss)
+    <!-- {.external} -->
+
+### Example
+
+<!-- no-catalog-start -->
+<!-- TODO: add image -->
+<!-- no-catalog-end -->
+<!-- catalog-only-start -->
+
+<!--
+
+<div class="figure-wrapper">
+  <figure
+      style="justify-content:center;"
+      aria-label="">
+    TODO: update figure
+  </figure>
+</div>
+
+-->
+
+<!-- catalog-only-end -->
+
+```html
+<style>
+:root {
+  /* System tokens */
+  --md-sys-color-surface-container-highest: #dde4e3;
+  --md-sys-color-on-surface: #161d1d;
+  --md-sys-color-on-surface-variant: #3f4948;
+  --md-sys-typescale-body-medium: system-ui 16px/24px;
+  --md-sys-typescale-headline-small: system-ui 24px/32px;
+
+  /* Component tokens */
+  --md-dialog-container-shape: 0px;
+}
+</style>
+
+<md-dialog>
+  <div slot="headline">Title</div>
+  <div slot="content">Dialog content</div>
+</md-dialog>
+```