0
# DOM Utilities
1

2
Kotlin-specific DOM manipulation utilities providing elegant, type-safe extensions for common DOM operations including CSS class management, element building, and browser global access.
3

4
## Capabilities
5

6
### Browser Globals
7

8
Direct access to global browser objects with full type safety.
9

10
```kotlin { .api }
11
/**
12
 * Global browser window object
13
 */
14
val window: Window
15

16
/**
17
 * Global DOM document object
18
 */
19
val document: Document
20

21
/**
22
 * Browser local storage API
23
 */
24
val localStorage: Storage
25

26
/**
27
 * Browser session storage API
28
 */
29
val sessionStorage: Storage
30
```
31

32
### Node Extensions
33

34
Type-safe extensions for DOM node operations and queries.
35

36
```kotlin { .api }
37
/**
38
 * Check if node is a text node or CDATA section
39
 */
40
val Node.isText: Boolean
41

42
/**
43
 * Check if node is an element node
44
 */
45
val Node.isElement: Boolean
46

47
/**
48
 * Remove all child nodes from this node
49
 */
50
fun Node.clear()
51
```
52

53
### Element Extensions
54

55
Enhanced element manipulation with Kotlin-style syntax and type safety.
56

57
```kotlin { .api }
58
/**
59
 * Create and append a text node to this element
60
 * @param text The text content to append
61
 * @return This element for chaining
62
 */
63
fun Element.appendText(text: String): Element
64
```
65

66
### CSS Class Management
67

68
Elegant CSS class manipulation with Kotlin collections syntax.
69

70
```kotlin { .api }
71
/**
72
 * Check if element has the specified CSS class
73
 * @param cssClass The CSS class name to check
74
 * @return true if the element has the class
75
 */
76
fun Element.hasClass(cssClass: String): Boolean
77

78
/**
79
 * Add one or more CSS classes to the element
80
 * @param cssClasses Variable number of CSS class names to add
81
 * @return true if any classes were added
82
 */
83
fun Element.addClass(vararg cssClasses: String): Boolean
84

85
/**
86
 * Remove one or more CSS classes from the element
87
 * @param cssClasses Variable number of CSS class names to remove
88
 * @return true if any classes were removed
89
 */
90
fun Element.removeClass(vararg cssClasses: String): Boolean
91
```
92

93
### Element Builders
94

95
DSL-style element creation with initialization blocks.
96

97
```kotlin { .api }
98
/**
99
 * Create an element with DSL-style initialization
100
 * @param name The tag name of the element to create
101
 * @param init Initialization block for configuring the element
102
 * @return The created element
103
 */
104
fun Document.createElement(name: String, init: Element.() -> Unit): Element
105

106
/**
107
 * Create and append a child element with DSL-style initialization
108
 * @param name The tag name of the element to create
109
 * @param init Initialization block for configuring the element
110
 * @return The created and appended element
111
 */
112
fun Element.appendElement(name: String, init: Element.() -> Unit): Element
113
```
114

115
### Storage Interface
116

117
Browser storage API for persistent and session data.
118

119
```kotlin { .api }
120
/**
121
 * Web Storage interface for localStorage and sessionStorage
122
 */
123
external interface Storage {
124
    /** The number of items in storage */
125
    val length: Int
126
    
127
    /** Get item value by key */
128
    fun getItem(key: String): String?
129
    /** Set item value */
130
    fun setItem(key: String, value: String)
131
    /** Remove item by key */
132
    fun removeItem(key: String)
133
    /** Clear all items */
134
    fun clear()
135
    /** Get key at index */
136
    fun key(index: Int): String?
137
}
138
```
139

140
### Deprecated API Aliases
141

142
Legacy API support with redirects to current implementations.
143

144
```kotlin { .api }
145
/**
146
 * Deprecated DOM utilities (redirect to kotlinx.dom)
147
 * These are maintained for backward compatibility
148
 */
149

150
// Deprecated in kotlin.dom package - use kotlinx.dom instead
151
@Deprecated("Use kotlinx.dom.isText", ReplaceWith("kotlinx.dom.isText"))
152
val kotlin.dom.Node.isText: Boolean
153

154
@Deprecated("Use kotlinx.dom.isElement", ReplaceWith("kotlinx.dom.isElement"))  
155
val kotlin.dom.Node.isElement: Boolean
156

157
@Deprecated("Use kotlinx.dom.clear", ReplaceWith("kotlinx.dom.clear"))
158
fun kotlin.dom.Node.clear()
159

160
@Deprecated("Use kotlinx.dom.appendText", ReplaceWith("kotlinx.dom.appendText"))
161
fun kotlin.dom.Element.appendText(text: String): Element
162

163
@Deprecated("Use kotlinx.dom.hasClass", ReplaceWith("kotlinx.dom.hasClass"))
164
fun kotlin.dom.Element.hasClass(cssClass: String): Boolean
165

166
@Deprecated("Use kotlinx.dom.addClass", ReplaceWith("kotlinx.dom.addClass"))
167
fun kotlin.dom.Element.addClass(vararg cssClasses: String): Boolean
168

169
@Deprecated("Use kotlinx.dom.removeClass", ReplaceWith("kotlinx.dom.removeClass"))
170
fun kotlin.dom.Element.removeClass(vararg cssClasses: String): Boolean
171

172
// Deprecated in kotlin.browser package - use kotlinx.browser instead
173
@Deprecated("Use kotlinx.browser.window", ReplaceWith("kotlinx.browser.window"))
174
val kotlin.browser.window: Window
175

176
@Deprecated("Use kotlinx.browser.document", ReplaceWith("kotlinx.browser.document"))
177
val kotlin.browser.document: Document
178

179
@Deprecated("Use kotlinx.browser.localStorage", ReplaceWith("kotlinx.browser.localStorage"))
180
val kotlin.browser.localStorage: Storage
181

182
@Deprecated("Use kotlinx.browser.sessionStorage", ReplaceWith("kotlinx.browser.sessionStorage"))
183
val kotlin.browser.sessionStorage: Storage
184
```
185

186
**Usage Examples:**
187

188
```kotlin
189
import kotlinx.browser.*
190
import kotlinx.dom.*
191
import org.w3c.dom.*
192

193
// Access browser globals
194
console.log("Current URL: ${window.location.href}")
195
console.log("Document title: ${document.title}")
196

197
// Create elements with DSL
198
val container = document.createElement("div") {
199
    id = "main-container"
200
    className = "container fluid"
201
    
202
    appendElement("h1") {
203
        textContent = "Welcome"
204
        addClass("title", "primary")
205
    }
206
    
207
    appendElement("p") {
208
        appendText("This is a paragraph with ")
209
        appendElement("strong") {
210
            textContent = "bold text"
211
        }
212
        appendText(".")
213
    }
214
    
215
    appendElement("button") {
216
        textContent = "Click me"
217
        addClass("btn", "btn-primary")
218
        
219
        addEventListener("click") {
220
            window.alert("Button clicked!")
221
        }
222
    }
223
}
224

225
document.body?.appendChild(container)
226

227
// CSS class management
228
val element = document.getElementById("myElement")
229
if (element != null) {
230
    // Check for classes
231
    if (element.hasClass("active")) {
232
        console.log("Element is active")
233
    }
234
    
235
    // Add classes
236
    element.addClass("highlight", "animated")
237
    
238
    // Remove classes
239
    element.removeClass("old-style", "deprecated")
240
    
241
    // Chain operations
242
    element.addClass("new-class")
243
           .appendText(" - Updated!")
244
}
245

246
// Node utilities
247
val textNodes = document.querySelectorAll("*").asList().filter { it.isText }
248
val elementNodes = document.querySelectorAll("*").asList().filter { it.isElement }
249

250
// Clear all children
251
val parent = document.getElementById("parent")
252
parent?.clear()
253

254
// Local storage operations
255
localStorage.setItem("user", "john_doe")
256
localStorage.setItem("preferences", JSON.stringify(mapOf(
257
    "theme" to "dark",
258
    "language" to "en"
259
)))
260

261
val user = localStorage.getItem("user")
262
val prefs = localStorage.getItem("preferences")?.let { JSON.parse<dynamic>(it) }
263

264
console.log("Stored user: $user")
265
console.log("Theme preference: ${prefs?.theme}")
266

267
// Session storage (same API as localStorage)
268
sessionStorage.setItem("session_id", "abc123")
269
val sessionId = sessionStorage.getItem("session_id")
270

271
// Complex DOM manipulation
272
fun createUserCard(name: String, email: String): Element {
273
    return document.createElement("div") {
274
        addClass("user-card", "shadow")
275
        
276
        appendElement("div") {
277
            addClass("user-header")
278
            
279
            appendElement("h3") {
280
                textContent = name
281
                addClass("user-name")
282
            }
283
            
284
            appendElement("p") {
285
                textContent = email
286
                addClass("user-email")
287
            }
288
        }
289
        
290
        appendElement("div") {
291
            addClass("user-actions")
292
            
293
            appendElement("button") {
294
                textContent = "Edit"
295
                addClass("btn", "btn-secondary")
296
            }
297
            
298
            appendElement("button") {
299
                textContent = "Delete"
300
                addClass("btn", "btn-danger")
301
            }
302
        }
303
    }
304
}
305

306
// Usage
307
val userCard = createUserCard("John Doe", "john@example.com")
308
document.getElementById("users-container")?.appendChild(userCard)
309

310
// Event delegation with DOM utilities
311
document.addEventListener("click") { event ->
312
    val target = event.target as? Element
313
    when {
314
        target?.hasClass("btn-delete") == true -> {
315
            target.closest(".user-card")?.remove()
316
        }
317
        target?.hasClass("btn-edit") == true -> {
318
            val card = target.closest(".user-card")
319
            card?.addClass("editing")
320
        }
321
    }
322
}
323
```