0
# Universal Inspector
1

2
The `Inspector` component serves as a universal interface that automatically selects the appropriate inspector type based on the provided data. It provides a single, convenient entry point for most inspection needs.
3

4
## Capabilities
5

6
### Inspector Component
7

8
Main universal component that automatically routes to the appropriate inspector based on data type and props.
9

10
```typescript { .api }
11
/**
12
 * Universal inspector component that automatically selects inspector type
13
 * @param props - Inspector configuration props
14
 * @returns React element with appropriate inspector (Object, Table, or DOM)
15
 */
16
function Inspector(props: InspectorProps): React.ReactElement;
17

18
interface InspectorProps {
19
  /** Data to inspect - any JavaScript value */
20
  data: any;
21
  /** When true, forces TableInspector regardless of data type */
22
  table?: boolean;
23
  /** Theme configuration - preset string or custom theme object */
24
  theme?: string | ThemeObject;
25
  
26
  // ObjectInspector-specific props (when table=false or auto-selected)
27
  /** Optional root node name */
28
  name?: string;
29
  /** Initial expansion level for ObjectInspector */
30
  expandLevel?: number;
31
  /** Paths to expand on initialization */
32
  expandPaths?: string | string[];
33
  /** Show non-enumerable properties */
34
  showNonenumerable?: boolean;
35
  /** Sort object keys */
36
  sortObjectKeys?: boolean | ((a: string, b: string) => number);
37
  /** Custom node renderer function */
38
  nodeRenderer?: (props: NodeRendererProps) => React.ReactElement;
39
  
40
  // TableInspector-specific props (when table=true)
41
  /** Column names for TableInspector */
42
  columns?: string[];
43
}
44
```
45

46
### Automatic Inspector Selection
47

48
The Inspector component uses the following logic to determine which inspector to use:
49

50
1. **Table Mode**: If `table={true}` → `TableInspector`
51
2. **DOM Node Detection**: If data is a DOM node → `DOMInspector`  
52
3. **Default**: Otherwise → `ObjectInspector`
53

54
```typescript
55
import React from "react";
56
import { Inspector } from "react-inspector";
57

58
// Automatic selection examples
59
const data = { name: "Alice", age: 30 };
60
const arrayData = [{ id: 1 }, { id: 2 }];
61
const domNode = document.getElementById("myDiv");
62

63
function AutoSelectionExamples() {
64
  return (
65
    <div>
66
      {/* Uses ObjectInspector (object data) */}
67
      <Inspector data={data} />
68
      
69
      {/* Uses ObjectInspector (array data, but table=false) */}
70
      <Inspector data={arrayData} />
71
      
72
      {/* Uses TableInspector (table=true forces table mode) */}
73
      <Inspector data={arrayData} table={true} />
74
      
75
      {/* Uses DOMInspector (DOM node detected) */}
76
      <Inspector data={domNode} />
77
    </div>
78
  );
79
}
80
```
81

82
### Universal Props Handling
83

84
The Inspector component intelligently passes props to the selected inspector:
85

86
**Common Props** (passed to all inspectors):
87
- `data`
88
- `theme`
89

90
**ObjectInspector Props** (passed when ObjectInspector is selected):
91
- `name`
92
- `expandLevel` 
93
- `expandPaths`
94
- `showNonenumerable`
95
- `sortObjectKeys`
96
- `nodeRenderer`
97

98
**TableInspector Props** (passed when TableInspector is selected):
99
- `columns`
100

101
**DOMInspector Props** (passed when DOMInspector is selected):
102
- `name`
103
- `expandLevel`
104
- `expandPaths`
105

106
```typescript
107
// Props are automatically routed to the correct inspector
108
function SmartPropsExample() {
109
  return (
110
    <div>
111
      {/* ObjectInspector receives expandLevel, sortObjectKeys */}
112
      <Inspector 
113
        data={{ z: 1, a: 2, b: 3 }}
114
        expandLevel={1}
115
        sortObjectKeys={true}
116
        columns={["irrelevant"]} // Ignored for ObjectInspector
117
      />
118
      
119
      {/* TableInspector receives columns */}
120
      <Inspector 
121
        data={[{ name: "Alice" }, { name: "Bob" }]}
122
        table={true}
123
        columns={["name"]}
124
        expandLevel={2} // Ignored for TableInspector
125
      />
126
    </div>
127
  );
128
}
129
```
130

131
### DOM Node Detection
132

133
The Inspector uses the `is-dom` library to detect DOM nodes and automatically switch to DOMInspector.
134

135
**DOM Node Types Detected:**
136
- Element nodes (DIV, SPAN, etc.)
137
- Text nodes
138
- Comment nodes  
139
- Document nodes
140
- Document fragments
141

142
```typescript
143
function DOMDetectionExample() {
144
  const element = document.createElement("div");
145
  element.innerHTML = "<span>Hello</span>";
146
  element.setAttribute("class", "example");
147
  
148
  return (
149
    <div>
150
      {/* Automatically uses DOMInspector */}
151
      <Inspector data={element} />
152
      
153
      {/* Can still override with table=true */}
154
      <Inspector data={element} table={true} />
155
    </div>
156
  );
157
}
158
```
159

160
### Usage Patterns
161

162
Common patterns for using the universal Inspector:
163

164
**Quick Debugging:**
165
```typescript
166
// Drop-in replacement for console.log
167
function debug(value: any, label?: string) {
168
  return <Inspector data={value} name={label} expandLevel={1} />;
169
}
170
```
171

172
**Conditional Display:**
173
```typescript
174
function ConditionalExample({ data, showAsTable }: { data: any, showAsTable: boolean }) {
175
  return (
176
    <Inspector 
177
      data={data} 
178
      table={showAsTable}
179
      expandLevel={showAsTable ? undefined : 1}
180
      columns={showAsTable ? ["name", "value"] : undefined}
181
    />
182
  );
183
}
184
```
185

186
**Multi-format Data Viewer:**
187
```typescript
188
function DataViewer({ data }: { data: any }) {
189
  const [viewMode, setViewMode] = useState<'auto' | 'table' | 'object'>('auto');
190
  
191
  const getInspectorProps = () => {
192
    switch (viewMode) {
193
      case 'table':
194
        return { table: true };
195
      case 'object':
196
        return { table: false, expandLevel: 1 };
197
      default:
198
        return {}; // Auto-detect
199
    }
200
  };
201
  
202
  return (
203
    <div>
204
      <select onChange={(e) => setViewMode(e.target.value as any)}>
205
        <option value="auto">Auto</option>
206
        <option value="table">Table</option>
207
        <option value="object">Object</option>
208
      </select>
209
      <Inspector data={data} {...getInspectorProps()} />
210
    </div>
211
  );
212
}
213
```
214

215
### Type Safety
216

217
The Inspector component maintains type safety through union types that ensure only valid prop combinations are accepted:
218

219
```typescript { .api }
220
type InspectorProps = TableInspectorProps | ObjectInspectorProps;
221

222
interface TableInspectorProps extends ComponentProps<typeof TableInspector> {
223
  table: true;
224
}
225

226
interface ObjectInspectorProps extends ComponentProps<typeof ObjectInspector> {
227
  table?: false;
228
}
229
```
230

231
This ensures that TypeScript will catch invalid prop combinations at compile time:
232

233
```typescript
234
// ✅ Valid - table mode with columns
235
<Inspector data={data} table={true} columns={["name"]} />
236

237
// ✅ Valid - object mode with expand level
238
<Inspector data={data} expandLevel={2} />
239

240
// ❌ TypeScript error - conflicting props
241
<Inspector data={data} table={true} expandLevel={2} />
242
```
243

244
### Performance Considerations
245

246
The Inspector component has minimal overhead since it simply routes to the appropriate inspector:
247

248
- **No re-rendering**: Inspector selection happens once per render
249
- **Props passing**: Direct prop forwarding to selected inspector
250
- **DOM detection**: Fast DOM node type checking via `is-dom`
251

252
For performance-critical applications, consider using the specific inspector components directly if the data type is known at compile time.