add events docs

Author: DerGoogler

docs/.vitepress/config/en.ts

@@ -116,6 +116,7 @@ function sidebarGuide() {
             },
             { text: "Index Setup", link: "/guide/webuix/index-setup" },
             { text: "Config", link: "/guide/webuix/config" },
+            { text: "Events", link: "/guide/webuix/events" },
             { text: "Sanitized Module ID's", link: "/guide/webuix/sanitized-ids" },
             { text: "Shortcuts", link: "/guide/webuix/shortcuts" },
           ],

docs/en/guide/webuix/events.md

@@ -1,50 +1,91 @@
 # WebUI X Events
 
-Events to help you handle states and navigation.
+WebUI X offers a flexible event system that enables your modules to handle UI states, navigation, and custom actions. This system empowers developers to create interactive and responsive user experiences within their modules.
 
-**Availability**
+## Availability
 
 > [!IMPORTANT]
-> This feature is in active development.
+> **WebUI X Events** are currently in active development.  
+> Feature support varies by platform:
+>
+> - **MMRL**: Supported from `v33661`
+> - **KernelSU Next**: Not supported
+> - **WebUI X: Portable**: Not supported
+> - **SukiSU Ultra**: Not supported
 
-- MMRL from `v33659`
-- KernelSU Next ❌
-- WebUI X: Portable ❌
-- SukiSU Ultra ❌
+## Enabling Event Handling
 
-_Enable_
+To enable event handling in your module, add the following options to your configuration file:
 
 ```jsonc
 {
-    // to enable `wxBack`
-    "backHandler": "js"
+  // Enables default back button handling (ignored if `backInterceptor` is set)
+  "backHandler": true,
+  // Use JavaScript to control back button behavior
+  "backInterceptor": "javascript"
 }
 ```
 
-```JavaScript
-// Handle incoming messages and dispatch them as events on `window`
-window.addEventListener("message", ({ data }) => {
-    console.log("Data received", data);
-    const event = new CustomEvent(data, { detail: data });
-    window.dispatchEvent(event);
+- **`backHandler`**: Enables the default back button handler.
+- **`backInterceptor`**: Allows you to intercept and handle back events in JavaScript. If both are set, `backInterceptor` takes precedence.
+
+## Usage Example
+
+You can listen for events using the `WXEvent` API from the `webuix` package. Below are examples for handling the back button and custom pause actions:
+
+```javascript
+import { WXEvent } from "webuix";
+
+// Initialize the event system (recommended for best compatibility)
+WXEvent.initialize();
+
+// Handle back event for a specific element (e.g., appDetails)
+WXEvent.on(appDetails, "back", (event) => {
+  if (appDetails.open) {
+    event.stopImmediatePropagation();
+    appDetails.open = false; // Close the details panel
+  }
 });
 
-// Listen for "wxBack" event
-window.addEventListener("wxBack", () => {
-    console.log("Called backEvent");
-    const p = prompt("Type 'leave' to close");
+// Handle back event at the window level
+WXEvent.on(window, "back", (event) => {
+  const appDetails = document.getElementById("appDetails");
+
+  if (appDetails?.open) {
+    appDetails.open = false;
+    return;
+  }
 
-    if (p === "leave") {
-        webui.exit();
-    } else {
-        alert("Seems that you can't type bro");
-    }
+  if (confirm("Close the app?")) {
+    webui.exit(); // Exit the WebUI app
+  }
 });
 
-// Listen for "wxPause" event
-window.addEventListener("wxPause", () => {
-    console.log("Called resumeEvent");
-    alert("Oh, hey! You're back?");
+// Example: Listen for a custom pause event (replace with your own logic)
+WXEvent.on(window, "pause", (event) => {
+  focusInput.focus();
+  statusEl.textContent = 'App paused - input focused';
+  statusEl.style.color = getCssVar('error');
 });
 
+// Listen for resume events
+WXEvent.on(window, "resume", (event) => {
+    statusEl.textContent = 'App resumed';
+    statusEl.style.color = getCssVar('success');
+    // Add any additional logic needed when the app resumes
+});
 ```
+
+### How It Works
+
+- The first handler listens for the `back` event on a specific element (`appDetails`). If the panel is open, it closes it and prevents the event from propagating further.
+- The second handler listens for the `back` event on the `window`. If no panels are open, it prompts the user to confirm exiting the app.
+- The third handler demonstrates listening for a custom `pause` event, updating UI elements as needed.
+
+---
+
+## Notes
+
+- If both `backHandler` and `backInterceptor` are set, `backInterceptor` will override the default handler.
+- Use `event.stopImmediatePropagation()` to prevent other handlers from executing for the same event.
+- The event system is designed to give you fine-grained control over navigation and state transitions in your WebUI modules.