0
# Event System
1

2
Comprehensive event handling system supporting all standard web events including mouse, keyboard, touch, pointer, focus, and custom events with full type safety and modern event patterns.
3

4
## Capabilities
5

6
### Core Event System
7

8
Base event interfaces and event target functionality for all DOM event handling.
9

10
```kotlin { .api }
11
/**
12
 * Base Event interface for all DOM events
13
 */
14
external class Event(type: String, eventInitDict: EventInit = definedExternally) {
15
    /** The event type */
16
    val type: String
17
    /** The event target */
18
    val target: EventTarget?
19
    /** The current event target during propagation */
20
    val currentTarget: EventTarget?
21
    /** The event phase (capturing, at target, bubbling) */
22
    val eventPhase: Short
23
    /** Whether the event bubbles */
24
    val bubbles: Boolean
25
    /** Whether the event is cancelable */
26
    val cancelable: Boolean
27
    /** Whether preventDefault has been called */
28
    val defaultPrevented: Boolean
29
    /** Whether the event is composed */
30
    val composed: Boolean
31
    /** Whether the event is trusted */
32
    val isTrusted: Boolean
33
    /** The event timestamp */
34
    val timeStamp: Double
35
    
36
    /** Prevent the default action */
37
    fun preventDefault()
38
    /** Stop event propagation */
39
    fun stopPropagation()
40
    /** Stop immediate event propagation */
41
    fun stopImmediatePropagation()
42
    /** Initialize the event (deprecated) */
43
    fun initEvent(type: String, bubbles: Boolean, cancelable: Boolean)
44
    
45
    companion object {
46
        const val NONE: Short = 0
47
        const val CAPTURING_PHASE: Short = 1
48
        const val AT_TARGET: Short = 2
49
        const val BUBBLING_PHASE: Short = 3
50
    }
51
}
52

53
/**
54
 * Event target interface for objects that can receive events
55
 */
56
external interface EventTarget {
57
    /** Add event listener */
58
    fun addEventListener(type: String, callback: EventListener?, options: dynamic = definedExternally)
59
    /** Remove event listener */
60
    fun removeEventListener(type: String, callback: EventListener?, options: dynamic = definedExternally)
61
    /** Dispatch event */
62
    fun dispatchEvent(event: Event): Boolean
63
}
64

65
/**
66
 * Event listener interface
67
 */
68
external interface EventListener {
69
    fun handleEvent(event: Event)
70
}
71

72
/**
73
 * Event initialization options
74
 */
75
external interface EventInit {
76
    var bubbles: Boolean?
77
    var cancelable: Boolean?
78
    var composed: Boolean?
79
}
80

81
/**
82
 * Add event listener options
83
 */
84
external interface AddEventListenerOptions : EventListenerOptions {
85
    var passive: Boolean?
86
    var once: Boolean?
87
    var signal: AbortSignal?
88
}
89

90
external interface EventListenerOptions {
91
    var capture: Boolean?
92
}
93
```
94

95
### UI Events
96

97
User interface events including focus, blur, and general UI interactions.
98

99
```kotlin { .api }
100
/**
101
 * UI Event for user interface interactions
102
 */
103
external class UIEvent(type: String, eventInitDict: UIEventInit = definedExternally) : Event {
104
    /** The view (window) where the event occurred */
105
    val view: Window?
106
    /** Additional detail about the event */
107
    val detail: Int
108
}
109

110
external interface UIEventInit : EventInit {
111
    var view: Window?
112
    var detail: Int?
113
}
114

115
/**
116
 * Focus events for element focus changes
117
 */
118
external class FocusEvent(type: String, eventInitDict: FocusEventInit = definedExternally) : UIEvent {
119
    /** The element losing or gaining focus */
120
    val relatedTarget: EventTarget?
121
}
122

123
external interface FocusEventInit : UIEventInit {
124
    var relatedTarget: EventTarget?
125
}
126
```
127

128
### Mouse Events
129

130
Complete mouse event handling including clicks, movement, and wheel events.
131

132
```kotlin { .api }
133
/**
134
 * Mouse events for mouse interactions
135
 */
136
external class MouseEvent(type: String, eventInitDict: MouseEventInit = definedExternally) : UIEvent {
137
    /** X coordinate relative to screen */
138
    val screenX: Int
139
    /** Y coordinate relative to screen */
140
    val screenY: Int
141
    /** X coordinate relative to client area */  
142
    val clientX: Int
143
    /** Y coordinate relative to client area */
144
    val clientY: Int
145
    /** Whether Ctrl key was pressed */
146
    val ctrlKey: Boolean
147
    /** Whether Shift key was pressed */
148
    val shiftKey: Boolean
149
    /** Whether Alt key was pressed */
150
    val altKey: Boolean
151
    /** Whether Meta key was pressed */
152
    val metaKey: Boolean
153
    /** Mouse button that was pressed */
154
    val button: Short
155
    /** Bitmask of pressed mouse buttons */
156
    val buttons: Short
157
    /** Related target element */
158
    val relatedTarget: EventTarget?
159
    
160
    /** Get modifier key state */
161
    fun getModifierState(keyArg: String): Boolean
162
    
163
    companion object {
164
        const val BUTTON_LEFT: Short = 0
165
        const val BUTTON_MIDDLE: Short = 1
166
        const val BUTTON_RIGHT: Short = 2
167
        const val BUTTON_BACK: Short = 3
168
        const val BUTTON_FORWARD: Short = 4
169
    }
170
}
171

172
external interface MouseEventInit : EventModifierInit {
173
    var screenX: Int?
174
    var screenY: Int?
175
    var clientX: Int?
176
    var clientY: Int?
177
    var button: Short?
178
    var buttons: Short?
179
    var relatedTarget: EventTarget?
180
}
181

182
/**
183
 * Wheel events for mouse wheel interactions
184
 */
185
external class WheelEvent(type: String, eventInitDict: WheelEventInit = definedExternally) : MouseEvent {
186
    /** Horizontal scroll delta */
187
    val deltaX: Double
188
    /** Vertical scroll delta */
189
    val deltaY: Double
190
    /** Z-axis scroll delta */
191
    val deltaZ: Double
192
    /** Delta mode (pixel, line, or page) */
193
    val deltaMode: Int
194
    
195
    companion object {
196
        const val DOM_DELTA_PIXEL: Int = 0
197
        const val DOM_DELTA_LINE: Int = 1
198
        const val DOM_DELTA_PAGE: Int = 2
199
    }
200
}
201

202
external interface WheelEventInit : MouseEventInit {
203
    var deltaX: Double?
204
    var deltaY: Double?
205
    var deltaZ: Double?
206
    var deltaMode: Int?
207
}
208
```
209

210
### Keyboard Events
211

212
Keyboard event handling with key codes, character input, and modifier keys.
213

214
```kotlin { .api }
215
/**
216
 * Keyboard events for key input
217
 */
218
external class KeyboardEvent(type: String, eventInitDict: KeyboardEventInit = definedExternally) : UIEvent {
219
    /** The key value */
220
    val key: String
221
    /** The physical key code */
222
    val code: String
223
    /** The key location */
224
    val location: Int
225
    /** Whether Ctrl key was pressed */
226
    val ctrlKey: Boolean
227
    /** Whether Shift key was pressed */
228
    val shiftKey: Boolean
229
    /** Whether Alt key was pressed */
230
    val altKey: Boolean
231
    /** Whether Meta key was pressed */
232
    val metaKey: Boolean
233
    /** Whether the key is being held down */
234
    val repeat: Boolean
235
    /** Whether the key is part of composition */
236
    val isComposing: Boolean
237
    
238
    /** Get modifier key state */
239
    fun getModifierState(keyArg: String): Boolean
240
    
241
    companion object {
242
        const val DOM_KEY_LOCATION_STANDARD: Int = 0
243
        const val DOM_KEY_LOCATION_LEFT: Int = 1
244
        const val DOM_KEY_LOCATION_RIGHT: Int = 2
245
        const val DOM_KEY_LOCATION_NUMPAD: Int = 3
246
    }
247
}
248

249
external interface KeyboardEventInit : EventModifierInit {
250
    var key: String?
251
    var code: String?
252
    var location: Int?
253
    var repeat: Boolean?
254
    var isComposing: Boolean?
255
}
256
```
257

258
### Input Events
259

260
Input events for text input and content editing.
261

262
```kotlin { .api }
263
/**
264
 * Input events for text input changes
265
 */
266
external class InputEvent(type: String, eventInitDict: InputEventInit = definedExternally) : UIEvent {
267
    /** The input data */
268
    val data: String?
269
    /** The data transfer object */
270
    val dataTransfer: DataTransfer?
271
    /** The input type */
272
    val inputType: String
273
    /** Whether the input is composing */
274
    val isComposing: Boolean
275
}
276

277
external interface InputEventInit : UIEventInit {
278
    var data: String?
279
    var dataTransfer: DataTransfer?
280
    var inputType: String?
281
    var isComposing: Boolean?
282
}
283

284
/**
285
 * Composition events for text composition
286
 */
287
external class CompositionEvent(type: String, eventInitDict: CompositionEventInit = definedExternally) : UIEvent {
288
    /** The composition data */
289
    val data: String
290
}
291

292
external interface CompositionEventInit : UIEventInit {
293
    var data: String?
294
}
295
```
296

297
### Pointer Events
298

299
Modern pointer events supporting mouse, touch, and pen input.
300

301
```kotlin { .api }
302
/**
303
 * Pointer events for unified input handling
304
 */
305
external class PointerEvent(type: String, eventInitDict: PointerEventInit = definedExternally) : MouseEvent {
306
    /** Unique pointer identifier */
307
    val pointerId: Int
308
    /** Contact width */
309
    val width: Double
310
    /** Contact height */
311
    val height: Double
312
    /** Contact pressure */
313
    val pressure: Float
314
    /** Tangential pressure */
315
    val tangentialPressure: Float
316
    /** X-axis tilt */
317
    val tiltX: Int
318
    /** Y-axis tilt */
319
    val tiltY: Int
320
    /** Pointer twist/rotation */
321
    val twist: Int
322
    /** Pointer type (mouse, pen, touch) */
323
    val pointerType: String
324
    /** Whether this is the primary pointer */
325
    val isPrimary: Boolean
326
}
327

328
external interface PointerEventInit : MouseEventInit {
329
    var pointerId: Int?
330
    var width: Double?
331
    var height: Double?
332
    var pressure: Float?
333
    var tangentialPressure: Float?
334
    var tiltX: Int?
335
    var tiltY: Int?
336
    var twist: Int?
337
    var pointerType: String?
338
    var isPrimary: Boolean?
339
}
340
```
341

342
### Touch Events
343

344
Touch events for mobile and touch-enabled devices.
345

346
```kotlin { .api }
347
/**
348
 * Touch events for touch input
349
 */
350
external class TouchEvent(type: String, eventInitDict: TouchEventInit = definedExternally) : UIEvent {
351
    /** List of current touches */
352
    val touches: TouchList
353
    /** List of touches on the target element */
354
    val targetTouches: TouchList
355
    /** List of changed touches */
356
    val changedTouches: TouchList
357
    /** Whether Alt key was pressed */
358
    val altKey: Boolean
359
    /** Whether Meta key was pressed */
360
    val metaKey: Boolean
361
    /** Whether Ctrl key was pressed */
362
    val ctrlKey: Boolean
363
    /** Whether Shift key was pressed */
364
    val shiftKey: Boolean
365
}
366

367
external interface TouchEventInit : EventModifierInit {
368
    var touches: Array<Touch>?
369
    var targetTouches: Array<Touch>?
370
    var changedTouches: Array<Touch>?
371
}
372

373
/**
374
 * Individual touch point
375
 */
376
external interface Touch {
377
    /** Touch identifier */
378
    val identifier: Int
379
    /** Touch target */
380
    val target: EventTarget
381
    /** Screen X coordinate */
382
    val screenX: Int
383
    /** Screen Y coordinate */
384
    val screenY: Int
385
    /** Client X coordinate */
386
    val clientX: Int
387
    /** Client Y coordinate */
388
    val clientY: Int
389
    /** Page X coordinate */
390
    val pageX: Int
391
    /** Page Y coordinate */
392
    val pageY: Int
393
    /** Touch radius X */
394
    val radiusX: Float
395
    /** Touch radius Y */
396
    val radiusY: Float
397
    /** Rotation angle */
398
    val rotationAngle: Float
399
    /** Touch pressure */
400
    val force: Float
401
}
402

403
/**
404
 * Collection of touches
405
 */
406
external interface TouchList : ItemArrayLike<Touch> {
407
    /** Get touch by identifier */
408
    fun identifiedTouch(identifier: Int): Touch?
409
}
410
```
411

412
### Drag and Drop Events
413

414
Drag and drop event handling for desktop interactions.
415

416
```kotlin { .api }
417
/**
418
 * Drag events for drag and drop operations
419
 */
420
external class DragEvent(type: String, eventInitDict: DragEventInit = definedExternally) : MouseEvent {
421
    /** The drag data transfer object */
422
    val dataTransfer: DataTransfer?
423
}
424

425
external interface DragEventInit : MouseEventInit {
426
    var dataTransfer: DataTransfer?
427
}
428

429
/**
430
 * Data transfer object for drag operations
431
 */
432
external interface DataTransfer {
433
    /** The drop effect */
434
    var dropEffect: String
435
    /** The effective allowed effect */
436
    var effectAllowed: String
437
    /** The drag items */
438
    val items: DataTransferItemList
439
    /** The drag types */
440
    val types: Array<String>
441
    /** The drag files */
442
    val files: FileList
443
    
444
    /** Clear drag data */
445
    fun clearData(format: String = definedExternally)
446
    /** Get drag data */
447
    fun getData(format: String): String
448
    /** Set drag data */
449
    fun setData(format: String, data: String)
450
    /** Set drag image */
451
    fun setDragImage(image: Element, x: Int, y: Int)
452
}
453

454
external interface DataTransferItemList : ItemArrayLike<DataTransferItem> {
455
    /** Add drag item */
456
    fun add(data: String, type: String): DataTransferItem?
457
    /** Add file item */
458
    fun add(data: File): DataTransferItem?
459
    /** Remove item */
460
    fun remove(index: Int)
461
    /** Clear all items */
462
    fun clear()
463
}
464

465
external interface DataTransferItem {
466
    /** Item kind */
467
    val kind: String
468
    /** Item type */
469
    val type: String
470
    /** Get item as string */
471
    fun getAsString(callback: ((String) -> Unit)?)
472
    /** Get item as file */
473
    fun getAsFile(): File?
474
}
475
```
476

477
### Custom Events
478

479
Support for creating and dispatching custom events.
480

481
```kotlin { .api }
482
/**
483
 * Custom events for application-specific events
484
 */
485
external class CustomEvent<T>(type: String, eventInitDict: CustomEventInit<T> = definedExternally) : Event {
486
    /** Custom event detail data */
487
    val detail: T
488
    
489
    /** Initialize custom event (deprecated) */
490
    fun initCustomEvent(type: String, bubbles: Boolean, cancelable: Boolean, detail: T)
491
}
492

493
external interface CustomEventInit<T> : EventInit {
494
    var detail: T?
495
}
496
```
497

498
### Event Utilities
499

500
Utility interfaces and helper functionality for event handling.
501

502
```kotlin { .api }
503
/**
504
 * Event modifier init interface
505
 */
506
external interface EventModifierInit : UIEventInit {
507
    var ctrlKey: Boolean?
508
    var shiftKey: Boolean?
509
    var altKey: Boolean?
510
    var metaKey: Boolean?
511
}
512

513
/**
514
 * Abort signal for canceling event listeners
515
 */
516
external interface AbortSignal : EventTarget {
517
    /** Whether the signal is aborted */
518
    val aborted: Boolean
519
    /** The abort reason */
520
    val reason: Any?
521
}
522

523
/**
524
 * Event listener factory function
525
 */
526
fun EventListener(handler: (Event) -> Unit): EventListener
527
```
528

529
**Usage Examples:**
530

531
```kotlin
532
import kotlinx.browser.document
533
import kotlinx.browser.window
534
import org.w3c.dom.events.*
535
import org.w3c.dom.*
536

537
// Basic event handling
538
val button = document.createElement("button") as HTMLButtonElement
539
button.textContent = "Click me"
540

541
button.addEventListener("click") { event ->
542
    val mouseEvent = event as MouseEvent
543
    console.log("Button clicked at (${mouseEvent.clientX}, ${mouseEvent.clientY})")
544
    event.preventDefault()
545
}
546

547
// Keyboard event handling
548
document.addEventListener("keydown") { event ->
549
    val keyEvent = event as KeyboardEvent
550
    when {
551
        keyEvent.ctrlKey && keyEvent.key == "s" -> {
552
            event.preventDefault()
553
            console.log("Save shortcut pressed")
554
        }
555
        keyEvent.key == "Escape" -> {
556
            console.log("Escape pressed")
557
        }
558
    }
559
}
560

561
// Touch event handling
562
val touchArea = document.getElementById("touch-area")
563
touchArea?.addEventListener("touchstart") { event ->
564
    val touchEvent = event as TouchEvent
565
    touchEvent.changedTouches.asList().forEach { touch ->
566
        console.log("Touch started at (${touch.clientX}, ${touch.clientY})")
567
    }
568
    event.preventDefault()
569
}
570

571
// Custom events
572
val customEvent = CustomEvent("myCustomEvent", object : CustomEventInit<String> {
573
    override var detail = "Hello from custom event"
574
    override var bubbles = true
575
})
576

577
document.addEventListener("myCustomEvent") { event ->
578
    val custom = event as CustomEvent<String>
579
    console.log("Custom event received: ${custom.detail}")
580
}
581

582
document.dispatchEvent(customEvent)
583

584
// Event delegation
585
document.addEventListener("click") { event ->
586
    val target = event.target as? Element
587
    if (target?.classList?.contains("button") == true) {
588
        console.log("Delegated button click")
589
    }
590
}
591

592
// Modern event listener options
593
button.addEventListener("click", object : AddEventListenerOptions {
594
    override var once = true
595
    override var passive = true
596
}) { event ->
597
    console.log("This listener will only fire once")
598
}
599
```