Add a usage example for alert dialogs

diff --git a/docs/javascript/components_dialog.md b/docs/javascript/components_dialog.md
index a706dd3c757eff57547180e0e0c8828e87198404..11c3620b33469f46809e6f91b256bb44bf2a0184 100644 (file)
--- a/docs/javascript/components_dialog.md
+++ b/docs/javascript/components_dialog.md
@@ -30,6 +30,7 @@ Alerts are designed to inform the user of something important that requires no f
 Typical examples for alerts are error messages or warnings.
 
 An alert will only provide a single button to acknowledge the dialog and must not contain interactive content.
+The dialog itself will be limited to a width of 500px, the title can wrap into multiple lines and there will be no „X“ button to close the dialog.
 
 ```ts
 const dialog = dialogFactory()
@@ -38,6 +39,25 @@ const dialog = dialogFactory()
 dialog.show("Server Error");
 ```
 
+You can customize the label of the primary button to better explain what will happen next.
+This can be useful for alerts that will have a side-effect when closing the dialog, such as redirect to a different page.
+
+```ts
+const dialog = dialogFactory()
+  .fromHtml("<p>Something went wrong, we cannot find your shopping cart.</p>")
+  .asAlert({
+    primary: "Back to the Store Page",
+  });
+
+dialog.addEventListener("primary", () => {
+  window.location.href = "https://example.com/shop/";
+});
+
+dialog.show("The shopping cart is missing");
+```
+
+The `primary` event is triggered both by clicking on the primary button and by clicks on the modal backdrop.
+
 ### When to Use
 
 Alerts are a special type of dialog that use the `role="alert"` attribute to signal its importance to assistive tools.