Improve docs on flash messages and alerts

Author: daftspunk

.vitepress/config.mjs

@@ -23,8 +23,8 @@ const sharedSidebar = [
             { text: 'Defining Components', link: '/guide/defining-components' },
             { text: 'Form Validation', link: '/guide/form-validation' },
             { text: 'Loading Indicators', link: '/guide/loading-indicators' },
-            { text: 'Downloads & Uploads', link: '/guide/download-upload' }
-            // { text: 'Flash Messages', link: '/guide/flash-messages' }
+            { text: 'Downloads & Uploads', link: '/guide/download-upload' },
+            { text: 'Flash Messages', link: '/guide/flash-messages' }
         ]
     },
     {

guide/flash-messages.md

@@ -1,51 +1,27 @@
 # Flash Messages
 
-Flash Messages are a handy way to let the user know the outcome of a request, either as a sucess or failure. Simply use the `Flash` facade to display a message after the request finishes. Flash messages are usually set inside AJAX handlers.
+Flash messages are a handy way to let the user know the outcome of a request, either as a success or failure. Use the `ajax()->flash()` method to display a message after the request finishes. Flash messages are usually set inside AJAX handlers.
 
 ```php
 function onSave()
 {
     // Sets a successful message
-    Flash::success('Settings successfully saved!');
-
-    // Sets an error message
-    Flash::error('Something went wrong...');
-
-    // Sets a warning message
-    Flash::warning('Please confirm your email address soon');
-
-    // Sets an informative message
-    Flash::info('The export is still processing. Please try again in a minute.');
+    return ajax()->flash('success', 'Settings successfully saved!');
 }
 ```
 
-Flash messages will disappear after an interval of 3 seconds. Clicking on a flash message will stop it from disappearing.
-
-## Built-in Flash Messages
-
-The AJAX framework has built-in support for flash messages, simply specify the `data-request-flash` attribute on a form to enable the use of flash messages on completed AJAX requests.
-
-```html
-<form
-    data-request="onSuccess"
-    data-request-flash>
-    <!-- Form Contents -->
-</form>
-```
-
-To only display a specific flash message type, you may pass the value to the attribute &mdash; **success**, **error**, **info**, **warning** or **validate**. Multiple values are separated by commas.
+The first argument is the message type: `success`, `error`, `warning`, or `info`.
 
-```html
-<form data-request-flash="success,warning"></form>
+```php
+function onSave()
+{
+    return ajax()
+        ->flash('success', 'Settings saved!')
+        ->flash('info', 'Remember to publish your changes.');
+}
 ```
 
-When using [validation features](../guide/form-validation.md) in combination with the `data-request-flash` attribute, the validation errors take priority and suppress the flash message. To display both at the same time, include the **validate** type with the attribute.
-
-```html
-<form
-    data-request-validate
-    data-request-flash="success,error,validate">
-```
+Flash messages will disappear after an interval of 3 seconds. Clicking on a flash message will stop it from disappearing.
 
 ### Loading Flash Message
 
@@ -92,3 +68,46 @@ jax.flashMsg({
     interval: 1
 });
 ```
+
+## Customizing Alerts
+
+When an AJAX request returns an error message, the framework triggers the `ajax:error-message` event before showing the native `alert()`. You can intercept this to use your own notification library.
+
+```js
+addEventListener('ajax:error-message', function(event) {
+    event.preventDefault();
+
+    Swal.fire({
+        icon: 'error',
+        title: 'Error',
+        text: event.detail.message
+    });
+});
+```
+
+## Customizing Confirms
+
+When a request has a `confirm` option (via `data-request-confirm` or the JavaScript API), the framework triggers the `ajax:confirm-message` event. The event detail includes a `promise` object that you must resolve or reject to continue or cancel the request.
+
+```js
+addEventListener('ajax:confirm-message', function(event) {
+    event.preventDefault();
+
+    const { message, promise } = event.detail;
+
+    Swal.fire({
+        title: 'Confirm',
+        text: message,
+        icon: 'warning',
+        showCancelButton: true,
+        confirmButtonText: 'Yes',
+        cancelButtonText: 'Cancel'
+    }).then((result) => {
+        result.isConfirmed ? promise.resolve() : promise.reject();
+    });
+});
+```
+
+::: tip
+For customizing loading indicators, see [Loading Indicators](./loading-indicators.md#working-with-javascript).
+:::

guide/loading-indicators.md

@@ -140,28 +140,69 @@ form[data-ajax-progress=onPay] .is-payment-loading {
 
 ## Working with JavaScript
 
-For more complex scenarios, you can hook in to the [JavaScript Events](../api/events/index.md) using the `ajax:promise` and `ajax:always` events. These events can be attached to the document, form or target elements.
+For more complex scenarios, you can hook in to the [JavaScript Events](../api/events/index.md) to build custom loading indicators.
+
+### Global Loader
+
+For a page-level loader (like a spinner in the header or full-page overlay), use the `ajax:request-start` and `ajax:request-end` events. These fire on every HTTP request.
 
 ```js
-formElement.addEventListener('ajax:promise', function() {
-    // A new request has started
+addEventListener('ajax:request-start', function() {
+    document.querySelector('#global-loader').classList.add('visible');
 });
 
-formElement.addEventListener('ajax:always', function() {
-    // A request has ended
+addEventListener('ajax:request-end', function() {
+    document.querySelector('#global-loader').classList.remove('visible');
+});
+```
+
+### Element-Specific Loader
+
+For loaders relative to the triggering element (like a spinner inside a button), use `ajax:before-request`, `ajax:request-complete`, and `ajax:request-cancel`. The cancel event fires when a confirmation dialog is declined, ensuring the loader is hidden even if the request never runs.
+
+```js
+document.addEventListener('ajax:before-request', function(event) {
+    if (event.detail?.context?.options?.loader === false) return;
+
+    const button = event.target.closest('button');
+    if (button) {
+        button.classList.add('loading');
+    }
 });
+
+function hideLoader(event) {
+    const button = event.target.closest('button');
+    if (button) {
+        button.classList.remove('loading');
+    }
+}
+
+document.addEventListener('ajax:request-complete', hideLoader);
+document.addEventListener('ajax:request-cancel', hideLoader);
+```
+
+To disable the loader for a specific request, set the `loader` option to `false`:
+
+```js
+jax.ajax('onDoSomething', { loader: false });
 ```
 
+```html
+<button data-request="onDoSomething" data-request-loader="false">Submit</button>
+```
+
+### Disabling Form Inputs
+
 The following example will disable all inputs inside a form while the request is running.
 
 ```js
-addEventListener('ajax:promise', function(event) {
+addEventListener('ajax:before-request', function(event) {
     event.target.closest('form').querySelectorAll('input').forEach(function(el) {
         el.disabled = true;
     });
 });
 
-addEventListener('ajax:always', function() {
+addEventListener('ajax:request-complete', function(event) {
     event.target.closest('form').querySelectorAll('input').forEach(function(el) {
         el.disabled = false;
     });