Add support for custom options and cancelable $dispatch

packages/alpinejs/src/utils/dispatch.js

@@ -1,12 +1,14 @@
 
-export function dispatch(el, name, detail = {}) {
-    el.dispatchEvent(
+export function dispatch(el, name, detail = {}, options = {}) {
+    return el.dispatchEvent(
         new CustomEvent(name, {
             detail,
             bubbles: true,
             // Allows events to pass the shadow DOM barrier.
             composed: true,
             cancelable: true,
+            // Allows overriding the default event options.
+            ...options
         })
     )
 }

packages/docs/src/en/magics/dispatch.md

@@ -104,3 +104,42 @@ You can also use `$dispatch()` to trigger data updates for `x-model` data bindin
 ```
 
 This opens up the door for making custom input components whose value can be set via `x-model`.
+
+<a name="cancelable-events"></a>
+## Cancelable events
+
+You can use the returned value of `$dispatch` to check if the event was canceled or not. This is useful when you want to prevent the default behavior of an action.
+
+```alpine
+<div x-data x-on:open="$event.preventDefault()">
+    <div x-data="{ open: false }">
+        <button @click="if($dispatch('open')){ open = true; }">Click me</button>
+        <!-- When the button is pressed an event is dispatched and only if the result is truthy (not prevented by any handler) the content will be shown. -->
+
+        <div x-show="open">
+            <h1>Hello</h1>
+        </div>
+    </div>
+</div>
+```
+
+This could be useful when you want to prevent opening/closing a modal or something like that by using event handlers.
+
+<a name="overwriting-options"></a>
+## Overwriting options
+
+You can use the third parameter of `$dispatch` to overwrite the default options of the event. For example, you can set `bubbles` to `false`:
+
+```alpine
+<!-- 🚫 Won't work because the event is being listened on the parent element -->
+<div x-data="{ title: 'Hello' }" x-on:update-title="title = $event.detail">
+    <button @click="$dispatch('update-title', 'Hello World!', {bubbles: false})">Click me</button>
+</div>
+
+<!-- ✅ Will work because the event is being listened on the same element -->
+<div x-data="{ title: 'Hello' }">
+    <button x-on:update-title="title = $event.detail" @click="$dispatch('update-title', 'Hello World!', {bubbles: false})">Click me</button>
+</div>
+```
+
+This is useful when you want to prevent the event from bubbling up to the parent elements.

tests/cypress/integration/magics/$dispatch.spec.js

@@ -14,3 +14,53 @@ test('$dispatch dispatches events properly',
         get('span').should(haveText('baz'))
     }
 )
+
+test('$dispatch with bubbles overwrite to false shouldn\'t bubble (event handling on parent)',
+    html`
+        <div x-data="{ foo: 'bar' }" x-on:custom-event="foo = $event.detail.newValue">
+            <span x-text="foo"></span>
+
+            <button x-on:click="$dispatch('custom-event', {newValue: 'baz'}, {bubbles: false})">click me</button>
+        </div>
+    `,
+    ({ get }) => {
+        get('span').should(haveText('bar'))
+        get('button').click()
+        get('span').should(haveText('bar'))
+    }
+)
+
+test('$dispatch with bubbles overwrite to false shouldn\'t bubble (event handling on same element)',
+    html`
+        <div x-data="{ foo: 'bar' }">
+            <span x-text="foo"></span>
+
+            <button
+                x-on:custom-event="foo = $event.detail.newValue"
+                x-on:click="$dispatch('custom-event', {newValue: 'baz'}, {bubbles: false})">click me</button>
+        </div>
+    `,
+    ({ get }) => {
+        get('span').should(haveText('bar'))
+        get('button').click()
+        get('span').should(haveText('baz'))
+    }
+)
+
+test('$dispatch cancelable should be cancelable by $event.preventDefault()',
+    html`
+        <div x-data="{ foo: 'bar' }"
+             x-on:prevented-event="$event.preventDefault()">
+            <span x-text="foo"></span>
+
+            <button x-on:click="if($dispatch('not-prevented-event')){ foo = 'baz'; } if($dispatch('prevented-event')){ foo = 'bar'; }">
+                click me
+            </button>
+        </div>
+    `,
+    ({ get }) => {
+        get('span').should(haveText('bar'))
+        get('button').click()
+        get('span').should(haveText('baz'))
+    }
+)