0
# DOM Utilities
1

2
Comprehensive DOM manipulation utilities covering CSS operations, event handling, focus management, and cross-browser compatibility for element measurement and styling.
3

4
## Capabilities
5

6
### Environment Detection
7

8
#### canUseDom
9

10
Checks if DOM APIs are available (browser environment detection).
11

12
```javascript { .api }
13
/**
14
 * Check if DOM is available (browser environment)
15
 * @returns {boolean} True if DOM APIs are available
16
 */
17
function canUseDom(): boolean;
18
```
19

20
**Usage Example:**
21

22
```javascript
23
import canUseDom from 'rc-util/lib/Dom/canUseDom';
24

25
if (canUseDom()) {
26
  // Safe to use DOM APIs
27
  document.getElementById('app');
28
} else {
29
  // Server-side rendering or non-browser environment
30
  console.log('DOM not available');
31
}
32
```
33

34
### Event Handling
35

36
#### addEventListener
37

38
Enhanced DOM event listener with React batched updates support.
39

40
```javascript { .api }
41
/**
42
 * Add DOM event listener with React batched updates
43
 * @param {ReactNode} target - Target element or React node
44
 * @param {string} eventType - Event type (e.g., 'click', 'scroll')
45
 * @param {Function} callback - Event handler function
46
 * @param {any} [option] - Event listener options
47
 * @returns {{ remove: Function }} Object with remove method
48
 */
49
function addEventListener(
50
  target: ReactNode, 
51
  eventType: string, 
52
  callback: Function, 
53
  option?: any
54
): { remove: Function };
55
```
56

57
**Usage Example:**
58

59
```javascript
60
import addEventListener from 'rc-util/lib/Dom/addEventListener';
61

62
// Add click listener with batched updates
63
const listener = addEventListener(
64
  document.body,
65
  'click',
66
  (e) => {
67
    // This will be batched with other React updates
68
    setClicked(true);
69
  }
70
);
71

72
// Remove listener when done
73
listener.remove();
74
```
75

76
### CSS Class Manipulation
77

78
#### class
79

80
Cross-browser CSS class manipulation utilities with fallbacks for older browsers.
81

82
```javascript { .api }
83
/**
84
 * Check if element has a CSS class
85
 * @param {HTMLElement} node - Target element
86
 * @param {string} className - Class name to check
87
 * @returns {boolean} True if element has the class
88
 */
89
function hasClass(node: HTMLElement, className: string): boolean;
90

91
/**
92
 * Add CSS class to element
93
 * @param {HTMLElement} node - Target element
94
 * @param {string} className - Class name to add
95
 */
96
function addClass(node: HTMLElement, className: string): void;
97

98
/**
99
 * Remove CSS class from element
100
 * @param {HTMLElement} node - Target element
101
 * @param {string} className - Class name to remove
102
 */
103
function removeClass(node: HTMLElement, className: string): void;
104
```
105

106
**Usage Example:**
107

108
```javascript
109
import { hasClass, addClass, removeClass } from 'rc-util/lib/Dom/class';
110

111
const element = document.getElementById('myDiv');
112

113
// Check class
114
if (hasClass(element, 'active')) {
115
  console.log('Element is active');
116
}
117

118
// Add class
119
addClass(element, 'highlighted');
120

121
// Remove class
122
removeClass(element, 'hidden');
123
```
124

125
### Element Relationships
126

127
#### contains
128

129
Checks if a node is equal to root or exists within root's subtree.
130

131
```javascript { .api }
132
/**
133
 * Check if node is equal to root or in root's subtree
134
 * @param {HTMLElement} root - Root element to check within
135
 * @param {HTMLElement} node - Node to search for
136
 * @returns {boolean} True if node is root or descendant of root
137
 */
138
function contains(root: HTMLElement, node: HTMLElement): boolean;
139
```
140

141
**Usage Example:**
142

143
```javascript
144
import contains from 'rc-util/lib/Dom/contains';
145

146
const container = document.getElementById('container');
147
const childElement = document.getElementById('child');
148

149
if (contains(container, childElement)) {
150
  console.log('Child is inside container');
151
}
152
```
153

154
### CSS and Layout
155

156
#### css
157

158
Comprehensive CSS and layout measurement utilities for getting and setting styles.
159

160
```javascript { .api }
161
/**
162
 * Get computed style value(s) from element
163
 * @param {HTMLElement} node - Target element
164
 * @param {string} [name] - Style property name (optional)
165
 * @returns {any} Style value or all computed styles
166
 */
167
function get(node: HTMLElement, name?: string): any;
168

169
/**
170
 * Set CSS style(s) on element
171
 * @param {HTMLElement} node - Target element
172
 * @param {string|object} name - Style property name or styles object
173
 * @param {any} [value] - Style value (when name is string)
174
 * @returns {any} Set value or computed styles
175
 */
176
function set(node: HTMLElement, name: string | object, value?: any): any;
177

178
/**
179
 * Get element's outer width including borders and scrollbar
180
 * @param {HTMLElement} el - Target element
181
 * @returns {number} Outer width in pixels
182
 */
183
function getOuterWidth(el: HTMLElement): number;
184

185
/**
186
 * Get element's outer height including borders and scrollbar
187
 * @param {HTMLElement} el - Target element
188
 * @returns {number} Outer height in pixels
189
 */
190
function getOuterHeight(el: HTMLElement): number;
191

192
/**
193
 * Get document dimensions
194
 * @returns {{ width: number, height: number }} Document size
195
 */
196
function getDocSize(): { width: number, height: number };
197

198
/**
199
 * Get client viewport dimensions
200
 * @returns {{ width: number, height: number }} Client size
201
 */
202
function getClientSize(): { width: number, height: number };
203

204
/**
205
 * Get current scroll position
206
 * @returns {{ scrollLeft: number, scrollTop: number }} Scroll position
207
 */
208
function getScroll(): { scrollLeft: number, scrollTop: number };
209

210
/**
211
 * Get element's offset position relative to document
212
 * @param {HTMLElement} node - Target element
213
 * @returns {{ left: number, top: number }} Offset position
214
 */
215
function getOffset(node: HTMLElement): { left: number, top: number };
216
```
217

218
**Usage Examples:**
219

220
```javascript
221
import { get, set, getOuterWidth, getOffset } from 'rc-util/lib/Dom/css';
222

223
const element = document.getElementById('myDiv');
224

225
// Get styles
226
const width = get(element, 'width'); // "100px"
227
const allStyles = get(element); // All computed styles
228

229
// Set styles
230
set(element, 'color', 'red');
231
set(element, { color: 'blue', fontSize: '16px' });
232

233
// Measurements
234
const outerWidth = getOuterWidth(element); // 120 (including borders)
235
const position = getOffset(element); // { left: 100, top: 50 }
236
```
237

238
### Focus Management
239

240
#### focus
241

242
Focus management utilities for accessibility and keyboard navigation.
243

244
```javascript { .api }
245
/**
246
 * Get list of focusable elements within a container
247
 * @param {HTMLElement} node - Container element
248
 * @returns {HTMLElement[]} Array of focusable elements
249
 */
250
function getFocusNodeList(node: HTMLElement): HTMLElement[];
251

252
/**
253
 * Save the currently focused element for later restoration
254
 */
255
function saveLastFocusNode(): void;
256

257
/**
258
 * Clear the saved focus element
259
 */
260
function clearLastFocusNode(): void;
261

262
/**
263
 * Restore focus to the previously saved element
264
 */
265
function backLastFocusNode(): void;
266

267
/**
268
 * Limit tab navigation within a container (focus trap)
269
 * @param {HTMLElement} node - Container element
270
 * @param {Event} e - Keyboard event
271
 */
272
function limitTabRange(node: HTMLElement, e: Event): void;
273
```
274

275
**Usage Example:**
276

277
```javascript
278
import { 
279
  getFocusNodeList, 
280
  saveLastFocusNode, 
281
  backLastFocusNode,
282
  limitTabRange 
283
} from 'rc-util/lib/Dom/focus';
284

285
// Modal focus management
286
function openModal() {
287
  saveLastFocusNode(); // Save current focus
288
  // Show modal and focus first element
289
}
290

291
function closeModal() {
292
  backLastFocusNode(); // Restore previous focus
293
}
294

295
// Trap focus within modal
296
function handleModalKeyDown(e) {
297
  limitTabRange(modalElement, e);
298
}
299

300
// Get focusable elements
301
const focusableElements = getFocusNodeList(containerElement);
302
```
303

304
### Feature Detection
305

306
#### support
307

308
Feature detection for CSS animations and transitions.
309

310
```javascript { .api }
311
/**
312
 * Animation support detection
313
 * @type {boolean | { end: string }} False if not supported, or object with event name
314
 */
315
const animation: boolean | { end: string };
316

317
/**
318
 * Transition support detection  
319
 * @type {boolean | { end: string }} False if not supported, or object with event name
320
 */
321
const transition: boolean | { end: string };
322
```
323

324
**Usage Example:**
325

326
```javascript
327
import { animation, transition } from 'rc-util/lib/Dom/support';
328

329
// Check animation support
330
if (animation) {
331
  element.addEventListener(animation.end, handleAnimationEnd);
332
  element.classList.add('animate');
333
}
334

335
// Check transition support
336
if (transition) {
337
  element.addEventListener(transition.end, handleTransitionEnd);
338
  element.style.transition = 'opacity 0.3s';
339
}
340
```
341

342
### Utilities
343

344
#### findDOMNode
345

346
React DOM node finding utility.
347

348
```typescript { .api }
349
/**
350
 * Find DOM node from React component or element
351
 * @param {any} node - React component or DOM element
352
 * @returns {HTMLElement | null} DOM element or null
353
 */
354
function findDOMNode(node: any): HTMLElement | null;
355
```