0
# DOM Inspector
1

2
Specialized inspector for DOM nodes that displays the DOM tree structure with proper HTML element representation. Designed for examining DOM nodes in a hierarchical tree format similar to browser developer tools.
3

4
## Capabilities
5

6
### DOMInspector Component
7

8
Main component for inspecting DOM nodes with appropriate tree structure and HTML formatting.
9

10
```typescript { .api }
11
/**
12
 * Inspector for DOM nodes displaying HTML tree structure
13
 * @param props - DOMInspector configuration props
14
 * @returns React element displaying the DOM tree
15
 */
16
function DOMInspector(props: DOMInspectorProps): React.ReactElement;
17

18
interface DOMInspectorProps {
19
  /** DOM Node to inspect - Element, Text, Comment, Document, etc. */
20
  data: Node;
21
  /** Theme configuration - preset string or custom theme object */
22
  theme?: string | ThemeObject;
23
  /** Optional root node name */
24
  name?: string;
25
  /** Initial expansion level - 0 means collapsed, 1 expands first level, etc. */
26
  expandLevel?: number;
27
  /** 
28
   * Paths to expand on initialization - JSONPath-style strings or array
29
   * Example: ["$", "$.0", "$.0.1"] to expand specific child nodes
30
   */
31
  expandPaths?: string | string[];
32
}
33
```
34

35
**Usage Examples:**
36

37
```typescript
38
import React, { useRef, useEffect } from "react";
39
import { DOMInspector } from "react-inspector";
40

41
// Inspect a DOM element
42
function BasicDOMExample() {
43
  const divRef = useRef<HTMLDivElement>(null);
44
  
45
  useEffect(() => {
46
    if (divRef.current) {
47
      // Add some content to inspect
48
      divRef.current.innerHTML = `
49
        <span class="greeting">Hello</span>
50
        <p id="message">World!</p>
51
      `;
52
    }
53
  }, []);
54
  
55
  return (
56
    <div>
57
      <div ref={divRef} className="demo-content" />
58
      {divRef.current && (
59
        <DOMInspector 
60
          data={divRef.current} 
61
          name="demoDiv"
62
          expandLevel={2}
63
        />
64
      )}
65
    </div>
66
  );
67
}
68

69
// Inspect document or other DOM objects
70
function DocumentExample() {
71
  return (
72
    <DOMInspector 
73
      data={document.documentElement} 
74
      name="document.documentElement"
75
      expandLevel={1}
76
    />
77
  );
78
}
79
```
80

81
### DOM Node Types Support
82

83
DOMInspector handles all standard DOM node types appropriately:
84

85
**Element Nodes (Node.ELEMENT_NODE = 1):**
86
- Display as HTML tags: `<div>`, `<span>`, `<p>`, etc.
87
- Show attributes as properties
88
- Display child elements in tree structure
89
- Include closing tags for elements with children
90

91
**Text Nodes (Node.TEXT_NODE = 3):**
92
- Display text content
93
- Skip empty whitespace-only text nodes
94
- Show actual text values inline for elements with simple text content
95

96
**Comment Nodes (Node.COMMENT_NODE = 8):**
97
- Display as HTML comments: `<!-- comment text -->`
98
- Preserved in tree structure
99

100
**Document Nodes (Node.DOCUMENT_NODE = 9):**
101
- Display document structure
102
- Show document properties and child nodes
103

104
**Document Fragment Nodes (Node.DOCUMENT_FRAGMENT_NODE = 11):**
105
- Display fragment contents
106
- Show all child nodes
107

108
### HTML Element Representation
109

110
DOM elements are displayed with proper HTML syntax and styling:
111

112
```typescript { .api }
113
// Element display format examples:
114
// <div class="container" id="main">
115
//   <span>Hello</span>
116
//   <p>World</p>
117
// </div>
118

119
// Self-closing elements:
120
// <img src="image.jpg" alt="Description" />
121
// <br />
122

123
// Elements with attributes:
124
// <input type="text" value="example" data-id="123" />
125
```
126

127
**Attribute Handling:**
128
- All attributes displayed with proper syntax
129
- Attribute names and values properly styled
130
- Boolean attributes handled correctly
131
- Data attributes and custom attributes included
132

133
### Text Content Inlining
134

135
DOMInspector intelligently handles text content display:
136

137
**Inline Text**: Simple text content is displayed inline with the element
138
```html
139
<span>Simple text</span>  <!-- Text shown inline -->
140
```
141

142
**Complex Content**: Elements with multiple children show expanded structure
143
```html
144
<div>
145
  <span>Child 1</span>
146
  <span>Child 2</span>
147
</div>
148
```
149

150
**Whitespace Handling**: Empty whitespace-only text nodes are automatically filtered out to reduce clutter.
151

152
### Tree Node Naming
153

154
DOM nodes are labeled in the tree using a specific naming convention:
155

156
```typescript { .api }
157
// Node naming format: TAGNAME[index]
158
// Examples:
159
// DIV[0] - First div child
160
// SPAN[1] - Second span child  
161
// P[0] - First paragraph child
162
// CLOSE_TAG - Closing tag marker for elements with children
163
```
164

165
### Expansion Control
166

167
Control which parts of the DOM tree are initially expanded:
168

169
```typescript
170
// Expand specific DOM paths
171
<DOMInspector 
172
  data={domElement}
173
  expandPaths={[
174
    "$",           // Root element
175
    "$.0",         // First child
176
    "$.0.1",       // Second child of first child
177
  ]}
178
/>
179

180
// Expand to show element structure
181
<DOMInspector 
182
  data={domElement}
183
  expandLevel={2}  // Show 2 levels deep
184
/>
185
```
186

187
### Styling and Themes
188

189
DOMInspector uses specialized theme variables for HTML element styling:
190

191
```typescript { .api }
192
interface DOMThemeVariables {
193
  /** Color for HTML tag brackets < > */
194
  HTML_TAG_COLOR?: string;
195
  /** Color for tag names (div, span, p, etc.) */
196
  HTML_TAGNAME_COLOR?: string;
197
  /** Text transform for tag names (uppercase, lowercase, none) */
198
  HTML_TAGNAME_TEXT_TRANSFORM?: string;
199
  /** Color for attribute names (class, id, src, etc.) */
200
  HTML_ATTRIBUTE_NAME_COLOR?: string;
201
  /** Color for attribute values */
202
  HTML_ATTRIBUTE_VALUE_COLOR?: string;
203
  /** Color for HTML comments */
204
  HTML_COMMENT_COLOR?: string;
205
  /** Color for DOCTYPE declarations */
206
  HTML_DOCTYPE_COLOR?: string;
207
}
208
```
209

210
**Default Chrome Light Theme Colors:**
211
- Tag brackets: Gray (#888)
212
- Tag names: Purple (#881280)
213
- Attribute names: Brown (#994500)
214
- Attribute values: Blue (#1a1aa6)
215
- Comments: Gray (#708090)
216

217
### Practical Use Cases
218

219
**Development Tools:**
220
```typescript
221
// Create a DOM inspector tool for debugging
222
function DOMDebugger({ selector }: { selector: string }) {
223
  const element = document.querySelector(selector);
224
  
225
  if (!element) {
226
    return <div>Element not found: {selector}</div>;
227
  }
228
  
229
  return (
230
    <div>
231
      <h3>DOM Inspector: {selector}</h3>
232
      <DOMInspector 
233
        data={element}
234
        expandLevel={1}
235
        theme="chromeDark"
236
      />
237
    </div>
238
  );
239
}
240
```
241

242
**Component Structure Analysis:**
243
```typescript
244
// Inspect React component DOM output
245
function ComponentInspector({ children }: { children: React.ReactNode }) {
246
  const containerRef = useRef<HTMLDivElement>(null);
247
  
248
  return (
249
    <div>
250
      <div ref={containerRef}>
251
        {children}
252
      </div>
253
      {containerRef.current && (
254
        <details>
255
          <summary>DOM Structure</summary>
256
          <DOMInspector 
257
            data={containerRef.current}
258
            expandLevel={3}
259
          />
260
        </details>
261
      )}
262
    </div>
263
  );
264
}
265
```
266

267
### Performance Considerations
268

269
For large DOM trees:
270
- Use limited `expandLevel` to avoid rendering too many nodes initially
271
- Consider the size of the DOM subtree being inspected
272
- Text content inlining reduces node count for simple elements
273
- Whitespace filtering improves readability and performance
274

275
### Browser Compatibility
276

277
DOMInspector works with standard DOM APIs available in all modern browsers:
278
- Uses `Node.childNodes` for tree traversal
279
- Checks `Node.nodeType` for type determination  
280
- Accesses `Node.textContent` for text nodes
281
- Uses element properties for attributes and tag names