0
# Utilities
1

2
Helper function for DOM event dispatching with cross-browser compatibility.
3

4
## Capabilities
5

6
### Event Dispatching
7

8
Custom DOM event creation and dispatching with cross-browser compatibility. This is the only utility function exported from the main package.
9

10
```javascript { .api }
11
/**
12
 * Dispatches custom DOM events with proper browser compatibility
13
 * Temporarily enables elements during dispatch to ensure event delivery
14
 * @param element - Target element for the event
15
 * @param type - Event type name
16
 * @param eventInit - Event configuration options
17
 * @returns The dispatched Event object
18
 */
19
function dispatchEvent(
20
  element: Element, 
21
  type: string, 
22
  eventInit?: {
23
    bubbles?: boolean;
24
    cancelable?: boolean;
25
    detail?: any;
26
  }
27
): Event;
28
```
29

30
**Usage Examples:**
31

32
```javascript
33
import { dispatchEvent } from "@rails/activestorage";
34

35
// Basic event dispatch
36
const button = document.querySelector("button");
37
dispatchEvent(button, "custom:click");
38

39
// Event with custom data
40
dispatchEvent(button, "upload:progress", {
41
  bubbles: true,
42
  cancelable: true,
43
  detail: {
44
    progress: 75,
45
    filename: "document.pdf",
46
    uploadId: 123
47
  }
48
});
49

50
// Listen for the custom event
51
button.addEventListener("upload:progress", (event) => {
52
  const { progress, filename } = event.detail;
53
  console.log(`${filename}: ${progress}%`);
54
});
55
```
56

57
### Cross-Browser Compatibility
58

59
The `dispatchEvent` function handles browser differences and provides consistent behavior across different environments.
60

61
**Implementation Details:**
62

63
```javascript
64
// Handles differences between:
65
// - Modern browsers: new CustomEvent()
66
// - Older browsers: document.createEvent() + initEvent()
67
// - Element state: temporarily enables disabled elements
68

69
function dispatchEvent(element, type, eventInit = {}) {
70
  const { disabled } = element;
71
  const { bubbles, cancelable, detail } = eventInit;
72
  
73
  // Use older event creation for maximum compatibility
74
  const event = document.createEvent("Event");
75
  event.initEvent(type, bubbles || true, cancelable || true);
76
  event.detail = detail || {};
77
  
78
  try {
79
    // Temporarily enable element to ensure event fires
80
    element.disabled = false;
81
    element.dispatchEvent(event);
82
  } finally {
83
    // Restore original disabled state
84
    element.disabled = disabled;
85
  }
86
  
87
  return event;
88
}
89
```
90

91
**Event Options:**
92

93
- `bubbles` (default: true) - Whether the event bubbles up through the DOM
94
- `cancelable` (default: true) - Whether the event can be cancelled
95
- `detail` - Custom data object attached to the event
96

97
**Temporary Element Enabling:**
98

99
The function temporarily enables disabled elements during event dispatch to ensure events are properly delivered. This is particularly important for form elements that may be disabled during upload processing but still need to receive and dispatch events.
100

101
**Usage in Active Storage:**
102

103
The `dispatchEvent` function is used internally by Active Storage controllers to dispatch upload lifecycle events:
104

105
```javascript
106
// Used by DirectUploadController
107
this.dispatch("start"); // Becomes dispatchEvent(this.input, "direct-upload:start", {...})
108
this.dispatch("progress", { progress: 75 }); // Becomes dispatchEvent(this.input, "direct-upload:progress", {...})
109
this.dispatch("error", { error: "Upload failed" }); // Becomes dispatchEvent(this.input, "direct-upload:error", {...})
110
```
111

112
This ensures consistent event handling across all browsers and provides a reliable way for applications to track upload progress and handle errors.