Document the API of dialogs

diff --git a/docs/javascript/components_confirmation.md b/docs/javascript/components_confirmation.md
index 091265402b53b1ba40f0293997a164b5deb427eb..5dc44f8a789847db1dc869d746c76e511bef183a 100644 (file)
--- a/docs/javascript/components_confirmation.md
+++ b/docs/javascript/components_confirmation.md
@@ -50,7 +50,7 @@ const askForReason = true;
 const { result, reason } = await confirmationFactory()
   .softDelete(theObjectName, askForReason);
 if (result) {
-    // …
+    console.log("The user has requested a soft delete, the following reason was provided:", reason);
 }
 ```
 
@@ -62,7 +62,7 @@ Restore a previously soft deleted object:
 const result = await confirmationFactory()
   .restore(theObjectName);
 if (result) {
-    // …
+    console.log("The user has requested to restore the object.");
 }
 ```
 
@@ -74,6 +74,10 @@ Permanently delete an object, will inform the user that the action cannot be und
 const result = await confirmationFactory()
   .delete(theObjectName);
 if (result) {
-    // …
+    console.log("The user has requested to delete the object.");
 }
 ```
+
+## Code Examples
+
+TODO

diff --git a/docs/javascript/components_dialog.md b/docs/javascript/components_dialog.md
index e30ce095acb6a47043b854dcc7c34332a1a60abc..9ad60ad42f1a096060faf2307c5c7cab9764680c 100644 (file)
--- a/docs/javascript/components_dialog.md
+++ b/docs/javascript/components_dialog.md
@@ -57,4 +57,103 @@ TODO
 
 ## Interacting with dialogs
 
+Dialogs are represented by the `<woltlab-core-dialog>` element that exposes a set of properties and methods to interact with it.
+
+### Opening and Closing Dialogs
+
+You can open a dialog through the `.show()` method that expects the title of the dialog as the only argument.
+Check the `.open` property to determine if the dialog is currently open.
+
+Programmatically closing a dialog is possibly through `.close()`.
+
+### Accessing the Content
+
+All contents of a dialog exists within a child element that can be accessed through the `content` property.
+
+```ts
+// Add some text to the dialog.
+const p = document.createElement("p");
+p.textContent = "Hello World";
+dialog.content.append(p);
+
+// Find a text input inside the dialog.
+const input = dialog.content.querySelector('input[type="text"]');
+```
+
+### Event Access
+
+You can bind event listeners to specialized events to get notified of events and to modify its behavior.
+
+#### `afterClose`
+
+_This event cannot be canceled._
+
+Fires when the dialog has closed.
+
+```ts
+dialog.addEventListener("afterClose", () => {
+  // Dialog was closed.
+});
+```
+
+#### `close`
+
+Fires when the dialog is about to close.
+
+```ts
+dialog.addEventListener("close", (event) => {
+  if (someCondition) {
+    event.preventDefault();
+  }
+});
+```
+
+#### `cancel`
+
+Fires only when there is a “Cancel” button and the user has either pressed that button or clicked on the modal backdrop.
+The dialog will close if the event is not canceled.
+
+```ts
+dialog.addEventListener("cancel", (event) => {
+  if (someCondition) {
+    event.preventDefault();
+  }
+});
+```
+
+#### `primary`
+
+_This event cannot be canceled._
+
+Fires only when there is a primary action button and the user has either pressed that button or submitted the form through keyboard controls.
+
+```ts
+dialog.addEventListener("primary", () => {
+  // The primary action button was clicked or the
+  // form was submitted through keyboard controls.
+  //
+  // The `validate` event has completed successfully.
+});
+```
+
+#### `validate`
+
+Fires only when there is a form and the user has pressed the primary action button or submitted the form through keyboard controls.
+Canceling this event is interpreted as a form validation failure.
+
+```ts
+const input = document.createElement("input");
+dialog.content.append(input);
+
+dialog.addEventListener("validate", (event) => {
+  if (input.value.trim() === "") {
+    event.preventDefault();
+
+    // Display an inline error message.
+  }
+});
+```
+
+## Code Examples
+
 TODO