AlpineJS Skill: Custom Events with `$dispatch`/`x-on`

$dispatch('eventName', { detail: 'data' })

This is Alpine's magic property used to dispatch a custom browser event from within an Alpine component.
- The first argument, 'eventName', is a string representing the name of your custom event (e.g., 'item-selected', 'update-cart').
- The second argument is an optional object containing the data you want to send with the event. Alpine automatically wraps this payload in the event.detail property. For example, if you dispatch $dispatch('user-action', { id: 1, type: 'click' }), the listener will access this data via event.detail.id and event.detail.type.

// Example: Dispatching an event with data
// <button @click="$dispatch('notify', { message: 'Hello there!' })">Send</button>

x-on:eventName="handleEvent" (shorthand: @eventName="handleEvent")

This directive is used to listen for DOM events on the element it's_applied to, or on its children (due to event bubbling for most events).
- When an event named eventName occurs, the JavaScript expression or method handleEvent is executed.
- The browser's native event object is automatically passed to your handler if it's a function call (e.g., handleEvent(event)). If it's an inline expression, event is available in its scope.

// Example: Listening for a custom event on a component
// <div x-data="{ message: '' }" @notify="message = event.detail.message">
//   Message: <span x-text="message"></span>
// </div>

x-on:eventName.window="handleGlobalEvent" (shorthand: @eventName.window="handleGlobalEvent")

This directive allows a component to listen for custom events dispatched on the global window object.
- This is crucial for communication between components that are not directly related in the DOM hierarchy (e.g., sibling components, or components in entirely different parts of the page).
- To dispatch a global event, you'd typically use vanilla JavaScript: window.dispatchEvent(new CustomEvent('eventName', { detail: 'data' })).

// Example: Listening for a global event
// <div x-data="{ alert: '' }" @system-alert.window="alert = event.detail.info">
//   System Alert: <span x-text="alert"></span>
// </div>

// JavaScript to dispatch a global event:
// window.dispatchEvent(new CustomEvent('system-alert', { detail: { info: 'Maintenance soon!' } }));

event.detail

When you dispatch a custom event with a data payload using $dispatch('eventName', { myData: 'value' }), AlpineJS (and standard browser behavior for CustomEvents) places this payload inside the detail property of the event object.
- In your event listener, you access this data via event.detail. For example, if the payload was { message: 'Saved!' }, you would access it as event.detail.message.

// Inside an event handler:
// function handleMyEvent(event) {
//   console.log(event.detail); // This is where your dispatched data resides
//   let specificData = event.detail.message;
// }

Events dispatched with $dispatch only bubble up the DOM tree by default.

This means an event dispatched by a child component can be caught by its parent, grandparent, and so on, up to the document root. However, it won't be caught by sibling components or "cousin" components directly.
- For sibling communication:
1. A common parent component can listen for the event from one child and then explicitly act on or inform the other sibling (e.g., by setting a shared state or dispatching another event downwards).
2. Alternatively, and often simpler for decoupled siblings, dispatch the event on the global window object: window.dispatchEvent(new CustomEvent('global-message', { detail: ... })). Then, any component can listen for it using @global-message.window="handler".
- Python developers might relate this to how exceptions bubble up call stacks, or how signals in a framework like Django or Qt work. Global window events are like a system-wide message bus, while standard $dispatch is more targeted to ancestors.

Forgetting to access data via event.detail.

When you dispatch data using $dispatch('myevent', { someKey: 'someValue' }), the data object ({ someKey: 'someValue' }) is not directly merged into the event object. It's always nested under the event.detail property.
- A common mistake is trying event.someKey instead of event.detail.someKey.
- Always remember: your payload is in event.detail.

// Correct way to access dispatched data:
// $dispatch('data-update', { user: 'Alice', score: 100 });
//
// In the listener:
// function handleUpdate(event) {
//   console.log(event.detail.user);  // 'Alice'
//   console.log(event.detail.score); // 100
// }

Overusing global window events for localized component communication.

While @event.window is powerful for cross-component communication, using it for everything can make your application's data flow harder to understand and debug, similar to over-relying on global variables in Python.
- For direct parent-child or child-parent interactions, standard $dispatch (which bubbles) and listening on the parent is often cleaner and more explicit about the communication path.
- Reserve window events for truly global notifications or when components are significantly decoupled. Python developers can think of this as choosing between a direct method call to a known object versus emitting a global signal: use the most direct and understandable mechanism appropriate for the context.