0
# Kotlin DOM API Compatibility
1

2
Kotlin DOM API Compatibility is a comprehensive library providing JavaScript interoperability and DOM manipulation utilities for Kotlin/JS applications. It bridges Kotlin type-safe programming with standard web APIs, offering complete W3C DOM bindings, HTML element interfaces, media handling, graphics support, and modern browser APIs.
3

4
## Package Information
5

6
- **Package Name**: kotlin-dom-api-compat
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: Add to `build.gradle.kts`: `implementation("org.jetbrains.kotlin:kotlin-dom-api-compat:1.9.25")`
10

11
## Core Imports
12

13
```kotlin
14
// Core DOM manipulation utilities
15
import kotlinx.dom.*
16
import kotlinx.browser.*
17

18
// W3C DOM APIs
19
import org.w3c.dom.*
20
import org.w3c.dom.events.*
21

22
// Media APIs
23
import org.w3c.dom.mediacapture.*
24
import org.w3c.files.*
25

26
// Graphics APIs  
27
import org.w3c.dom.svg.*
28
import org.khronos.webgl.*
29

30
// Networking APIs
31
import org.w3c.fetch.*
32
import org.w3c.xhr.*
33
```
34

35
## Basic Usage
36

37
```kotlin
38
import kotlinx.browser.document
39
import kotlinx.browser.window
40
import kotlinx.dom.*
41
import org.w3c.dom.HTMLButtonElement
42
import org.w3c.dom.events.Event
43

44
// Create and manipulate DOM elements
45
val button = document.createElement("button") {
46
    textContent = "Click me!"
47
    addClass("btn", "btn-primary")
48
}
49

50
// Add event handling
51
button.addEventListener("click") { event ->
52
    window.alert("Button clicked!")
53
}
54

55
// Append to document
56
document.body?.appendChild(button)
57

58
// DOM query and manipulation
59
val elements = document.querySelectorAll(".item")
60
elements.forEach { element ->
61
    element.addClass("processed")
62
    element.appendText("✓")
63
}
64
```
65

66
## Architecture
67

68
Kotlin DOM API Compatibility provides comprehensive W3C standards compliance with 500+ public API elements organized into several key areas:
69

70
- **Core DOM APIs** - Complete W3C DOM interfaces for document manipulation, element access, and node operations
71
- **HTML Elements** - Full HTML element hierarchy with type-safe property access and method calls
72
- **Event System** - Comprehensive event handling including mouse, keyboard, touch, and custom events
73
- **Media APIs** - Audio/video handling, media capture, streaming, and encrypted media support
74
- **Graphics APIs** - SVG manipulation (117+ classes) and WebGL rendering with typed arrays
75
- **Networking APIs** - Fetch API, XMLHttpRequest, headers, and CORS handling
76
- **Storage APIs** - File handling, blob manipulation, and browser storage access
77
- **Worker APIs** - Service workers, web workers, and cache management
78
- **Browser Integration** - Direct access to global browser objects and modern web APIs
79
- **DOM Utilities** - Kotlin-specific extensions for elegant DOM manipulation and CSS class management
80

81
## Capabilities
82

83
### Core DOM and HTML Elements
84

85
Complete W3C DOM API bindings with type-safe access to all HTML elements, document structure, and node operations. Includes extensive HTML element hierarchy with properties and methods.
86

87
```kotlin { .api }
88
// DOM access
89
val document: Document
90
val window: Window
91

92
// Element creation and manipulation
93
fun Document.createElement(name: String, init: Element.() -> Unit): Element
94
fun Element.appendElement(name: String, init: Element.() -> Unit): Element
95

96
// HTML element interfaces
97
interface HTMLElement : Element, GlobalEventHandlers, ElementContentEditable
98
interface HTMLButtonElement : HTMLElement
99
interface HTMLInputElement : HTMLElement
100
```
101

102
[Core DOM and HTML Elements](./org-w3c-dom.md)
103

104
### Event System
105

106
Comprehensive event handling system supporting all standard web events including mouse, keyboard, touch, pointer, focus, and custom events with full type safety.
107

108
```kotlin { .api }
109
interface Event {
110
    val type: String
111
    val target: EventTarget?
112
    val currentTarget: EventTarget?
113
    fun preventDefault()
114
    fun stopPropagation()
115
}
116

117
interface EventTarget {
118
    fun addEventListener(type: String, callback: EventListener?, options: dynamic = definedExternally)
119
    fun removeEventListener(type: String, callback: EventListener?, options: dynamic = definedExternally)
120
    fun dispatchEvent(event: Event): Boolean
121
}
122

123
class MouseEvent : UIEvent
124
class KeyboardEvent : UIEvent
125
class TouchEvent : UIEvent
126
```
127

128
[Event System](./org-w3c-events.md)
129

130
### Media APIs
131

132
Comprehensive media handling including audio/video elements, media capture (camera/microphone), media streaming, encrypted media extensions, and media source extensions.
133

134
```kotlin { .api }
135
interface MediaStream : EventTarget, MediaProvider {
136
    val active: Boolean
137
    val id: String
138
    fun getAudioTracks(): Array<MediaStreamTrack>
139
    fun getVideoTracks(): Array<MediaStreamTrack>
140
    fun addTrack(track: MediaStreamTrack)
141
    fun removeTrack(track: MediaStreamTrack)
142
}
143

144
interface MediaDevices : EventTarget {
145
    fun getUserMedia(constraints: MediaStreamConstraints = definedExternally): Promise<MediaStream>
146
    fun getDisplayMedia(constraints: MediaStreamConstraints = definedExternally): Promise<MediaStream>
147
    fun enumerateDevices(): Promise<Array<MediaDeviceInfo>>
148
}
149
```
150

151
[Media APIs](./org-w3c-additional.md#media-capture-and-streaming)
152

153
### Networking APIs
154

155
Modern networking capabilities including Fetch API for HTTP requests, XMLHttpRequest for legacy support, headers manipulation, and comprehensive CORS handling.
156

157
```kotlin { .api }
158
class Request(input: dynamic, init: RequestInit = definedExternally) : Body {
159
    val method: String
160
    val url: String
161
    val headers: Headers
162
    fun clone(): Request
163
}
164

165
class Response(body: dynamic = definedExternally, init: ResponseInit = definedExternally) : Body {
166
    val status: Short
167
    val statusText: String
168
    val ok: Boolean
169
    fun clone(): Response
170
}
171

172
class Headers(init: dynamic = definedExternally) {
173
    fun get(name: String): String?
174
    fun set(name: String, value: String)
175
    fun append(name: String, value: String)
176
    fun delete(name: String)
177
}
178
```
179

180
[Networking APIs](./org-w3c-networking.md)
181

182
### Additional Web APIs
183

184
Comprehensive collection of specialized APIs including media capture, file handling, SVG graphics, WebGL rendering, service workers, and web notifications.
185

186
```kotlin { .api }
187
// Media Capture
188
interface MediaStream : EventTarget, MediaProvider {
189
    val active: Boolean
190
    val id: String
191
    fun getAudioTracks(): Array<MediaStreamTrack>
192
    fun getVideoTracks(): Array<MediaStreamTrack>
193
}
194

195
// File API
196
class Blob(blobParts: Array<dynamic> = definedExternally, options: BlobPropertyBag = definedExternally) : MediaProvider
197
class File(fileBits: Array<dynamic>, fileName: String) : Blob
198

199
// SVG Graphics
200
interface SVGSVGElement : SVGGraphicsElement, SVGFitToViewBox
201
interface SVGPathElement : SVGGeometryElement
202

203
// WebGL
204
interface WebGLRenderingContext : WebGLRenderingContextBase
205
class Float32Array : ArrayBufferView
206

207
// Service Workers
208
interface ServiceWorker : EventTarget, AbstractWorker
209
interface Cache
210
class Notification : EventTarget
211
```
212

213
[Additional Web APIs](./org-w3c-additional.md)
214

215
### DOM Utilities
216

217
Kotlin-specific DOM manipulation utilities providing elegant, type-safe extensions for common DOM operations including CSS class management and element building.
218

219
```kotlin { .api }
220
// Extension properties
221
val Node.isText: Boolean
222
val Node.isElement: Boolean
223

224
// DOM manipulation
225
fun Node.clear()
226
fun Element.appendText(text: String): Element
227

228
// CSS class management  
229
fun Element.hasClass(cssClass: String): Boolean
230
fun Element.addClass(vararg cssClasses: String): Boolean
231
fun Element.removeClass(vararg cssClasses: String): Boolean
232

233
// Element builders
234
fun Document.createElement(name: String, init: Element.() -> Unit): Element
235
fun Element.appendElement(name: String, init: Element.() -> Unit): Element
236

237
// Browser globals
238
val window: Window
239
val document: Document
240
val localStorage: Storage
241
val sessionStorage: Storage
242
```
243

244
[DOM Utilities](./kotlinx-dom.md)
245

246
## Types
247

248
### Core Types
249

250
```kotlin { .api }
251
external interface Window : EventTarget, GlobalEventHandlers, WindowEventHandlers {
252
    val document: Document
253
    val location: Location
254
    val history: History
255
    val localStorage: Storage
256
    val sessionStorage: Storage
257
    fun alert(message: String)
258
    fun confirm(message: String): Boolean
259
    fun prompt(message: String, defaultText: String = definedExternally): String?
260
}
261

262
external interface Document : Node, DocumentOrShadowRoot, GlobalEventHandlers {
263
    val documentElement: Element?
264
    val head: HTMLHeadElement?
265
    val body: HTMLElement?
266
    fun createElement(localName: String): Element
267
    fun createTextNode(data: String): Text
268
    fun getElementById(elementId: String): Element?
269
    fun querySelector(selectors: String): Element?
270
    fun querySelectorAll(selectors: String): NodeList
271
}
272

273
external interface Element : Node, ChildNode, ParentNode, Slotable {
274
    val tagName: String
275
    val id: String
276
    val className: String
277
    val classList: DOMTokenList
278
    fun getAttribute(qualifiedName: String): String?
279
    fun setAttribute(qualifiedName: String, value: String)
280
    fun removeAttribute(qualifiedName: String)
281
    fun querySelector(selectors: String): Element?
282
    fun querySelectorAll(selectors: String): NodeList
283
}
284
```
285

286
### Event Types
287

288
```kotlin { .api }
289
external interface EventInit {
290
    var bubbles: Boolean?
291
    var cancelable: Boolean?
292
    var composed: Boolean?
293
}
294

295
external interface MouseEventInit : EventModifierInit {
296
    var screenX: Int?
297
    var screenY: Int?
298
    var clientX: Int?
299
    var clientY: Int?
300
    var button: Short?
301
    var buttons: Short?
302
    var relatedTarget: EventTarget?
303
}
304

305
external interface KeyboardEventInit : EventModifierInit {
306
    var key: String?
307
    var code: String?
308
    var location: Int?
309
    var repeat: Boolean?
310
    var isComposing: Boolean?
311
}
312
```
313

314
### Media Types
315

316
```kotlin { .api }
317
external interface MediaStreamConstraints {
318
    var video: dynamic
319
    var audio: dynamic
320
}
321

322
external interface MediaTrackConstraints {
323
    var width: dynamic
324
    var height: dynamic
325
    var aspectRatio: dynamic
326
    var frameRate: dynamic
327
    var facingMode: dynamic
328
    var deviceId: dynamic
329
}
330

331
external interface MediaDeviceInfo {
332
    val deviceId: String
333
    val kind: MediaDeviceKind
334
    val label: String
335
    val groupId: String
336
}
337
```