Refine "Modals" documentation: updated confirm dialog behavior and usage examples.

Author: bszyman

16/umbraco-cms/customizing/extending-overview/extension-types/modals/README.md

@@ -8,7 +8,7 @@ description: >-
 
 ## **Modal Types**
 
-The Dialog modal appears in the middle of the screen and the Sidebar Modal slides in from the right.
+The Dialog modal appears in the middle of the screen, and the Sidebar Modal slides in from the right.
 
 ## Open a Modal
 

16/umbraco-cms/customizing/extending-overview/extension-types/modals/confirm-dialog.md

@@ -1,47 +1,52 @@
 ---
-description: Ask the user for confirmation
+description: Present a dialog to ask the user for confirmation.
 ---
 
 # Confirm Dialog
 
-{% hint style="warning" %}
-This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice.
-{% endhint %}
+Confirmation dialogs are used to ask the user for confirmation to complete some action, and are presented as a
+center-aligned modal in the backoffice.
 
-This example shows how to open a confirm dialog. The `UMB_CONFIRM_MODAL` is a token that represents the confirm dialog. The `open` method takes the token and an object with the data for the confirm dialog. The `onSubmit` method returns a promise that resolves when the user confirms the dialog and rejects when the user cancels the dialog.
+Extension authors do not need to register the dialog in their extension's manifest, instead these dialogs are opened by
+importing and calling the `umbOpenModal` function.
 
-The confirm modal itself is built-in and does not need to be registered in the extension registry.
-
-The modal token describes the options that you can pass to the modal. The confirm modal token has the following properties:
+Extension authors can customize the dialog with several configuration options, such as the headline, body content,
+colors, and button labels.
 
 * `headline` - The headline of the modal.
 * `content` - The content of the modal, which can be a TemplateResult or a string.
-* `color` - (Optional) The color of the modal. This can be `positive` or `danger`.
-* `confirmLabel` - (Optional) The label of the confirm button.
+* `color` - (Optional) The color of the modal, can be `positive` or `danger`.
+* `confirmLabel` - (Optional) The label of the confirmation button.
+* `cancelLabel` - (Optional) The label of the cancel button.
+
+To see all properties of the `UMB_CONFIRM_MODAL` token, see the [API reference](https://apidocs.umbraco.com/v16/ui-api/interfaces/packages_core_modal.UmbConfirmModalData.html).
+
+The `onSubmit` method returns a promise that resolves when the user confirms the dialog, and rejects when the user
+cancels the dialog.
 
 ## Basic Usage
 
 {% code title="my-element.ts" %}
 ```typescript
-import { html, LitElement, customElement } from "@umbraco-cms/backoffice/external/lit";
-import { UmbElementMixin } from '@umbraco-cms/backoffice/element-api';
-import { umbOpenModal, UMB_CONFIRM_MODAL } from '@umbraco-cms/backoffice/modal';
-
-@customElement('my-element')
-export class MyElement extends UmbElementMixin(LitElement) {
+import {
+    html,
+    LitElement,
+    customElement,
+} from "@umbraco-cms/backoffice/external/lit";
+import { UmbElementMixin } from "@umbraco-cms/backoffice/element-api";
+import { umbOpenModal, UMB_CONFIRM_MODAL } from "@umbraco-cms/backoffice/modal";
 
+@customElement("my-confirmation-modal")
+export class MyConfirmationModal extends UmbElementMixin(LitElement) {
     #onRequestDisable() {
-        const modalContext = umbOpenModal(
-            this, UMB_CONFIRM_MODAL,
-            {
-                data: {
-                    headline: this.localize.term("actions_disable"),
-                    content: this.localize.term("defaultdialogs_confirmdisable"),
-                    color: "danger",
-                    confirmLabel: this.localize.term("actions_disable"),
-                }
-            }
-        )
+        umbOpenModal(this, UMB_CONFIRM_MODAL, {
+            data: {
+                headline: this.localize.term("actions_disable"),
+                content: this.localize.term("defaultdialogs_confirmdisable"),
+                color: "danger",
+                confirmLabel: this.localize.term("actions_disable"),
+            },
+        })
             .then(() => {
                 console.log("User has approved");
             })
@@ -52,10 +57,11 @@ export class MyElement extends UmbElementMixin(LitElement) {
 
     render() {
         return html`<uui-button
-                            look="primary"
-                            color="danger"
-                            @click=${this.#onRequestDisable}
-                            label=${this.localize.term("actions_disable")}></uui-button>`;
+      look="primary"
+      color="danger"
+      @click=${this.#onRequestDisable}
+      label=${this.localize.term("actions_disable")}
+    ></uui-button>`;
     }
 }
 ```