0
# Utility Components
1

2
Low-level components for building custom inspector interfaces and node renderers. These components provide the building blocks used by the main inspectors and can be used to create custom inspection UIs.
3

4
## Capabilities
5

6
### ObjectLabel
7

8
Renders object property labels with names and values, typically used for non-root tree nodes.
9

10
```typescript { .api }
11
/**
12
 * Renders object property labels with names and values
13
 * Used for displaying individual properties in object trees
14
 * @param props - ObjectLabel rendering props
15
 * @returns React element displaying property name and value
16
 */
17
function ObjectLabel(props: ObjectLabelProps): React.ReactElement;
18

19
interface ObjectLabelProps {
20
  /** Property name or key - string for object properties, number for array indices */
21
  name: string | number | any;
22
  /** Property value - any JavaScript value */
23
  data: any;
24
  /** Whether property is non-enumerable (affects styling - appears dimmed) */
25
  isNonenumerable?: boolean;
26
}
27
```
28

29
**Usage Examples:**
30

31
```typescript
32
import React from "react";
33
import { ObjectLabel } from "react-inspector";
34

35
// Basic property display
36
function BasicLabelExample() {
37
  return (
38
    <div>
39
      <ObjectLabel name="userName" data="Alice" />
40
      <ObjectLabel name="age" data={30} />
41
      <ObjectLabel name="isActive" data={true} />
42
    </div>
43
  );
44
}
45

46
// Non-enumerable property (dimmed)
47
function NonEnumerableExample() {
48
  return (
49
    <ObjectLabel 
50
      name="__proto__" 
51
      data={Object.prototype} 
52
      isNonenumerable={true}
53
    />
54
  );
55
}
56

57
// Array index
58
function ArrayIndexExample() {
59
  return (
60
    <ObjectLabel name={0} data="first item" />
61
  );
62
}
63
```
64

65
### ObjectRootLabel
66

67
Renders root object labels, used for the top-level node in object trees.
68

69
```typescript { .api }
70
/**
71
 * Renders root object labels for tree root nodes
72
 * Displays optional name and object preview
73
 * @param props - ObjectRootLabel rendering props  
74
 * @returns React element displaying root label
75
 */
76
function ObjectRootLabel(props: ObjectRootLabelProps): React.ReactElement;
77

78
interface ObjectRootLabelProps {
79
  /** Optional name for the root object */
80
  name?: string;
81
  /** Root object data */
82
  data: any;
83
}
84
```
85

86
**Usage Examples:**
87

88
```typescript
89
import React from "react";
90
import { ObjectRootLabel } from "react-inspector";
91

92
// Named root object
93
function NamedRootExample() {
94
  const userData = { name: "Alice", age: 30 };
95
  return <ObjectRootLabel name="user" data={userData} />;
96
}
97

98
// Unnamed root object (shows preview only)
99
function UnnamedRootExample() {
100
  const config = { apiUrl: "https://api.example.com", timeout: 5000 };
101
  return <ObjectRootLabel data={config} />;
102
}
103
```
104

105
### ObjectPreview
106

107
Renders compact previews of objects, showing type and structure overview.
108

109
```typescript { .api }
110
/**
111
 * Renders compact preview of objects showing type and brief content
112
 * Used for collapsed nodes and property values
113
 * @param props - ObjectPreview rendering props
114
 * @returns React element displaying object preview
115
 */
116
function ObjectPreview(props: ObjectPreviewProps): React.ReactElement;
117

118
interface ObjectPreviewProps {
119
  /** Object to generate preview for */
120
  data: any;
121
}
122
```
123

124
**Preview Format Examples:**
125

126
```typescript
127
// Array preview: (length) [item1, item2, ...]
128
[1, 2, 3] → "(3) [1, 2, 3]"
129
["a", "b"] → "(2) ['a', 'b']"
130

131
// Object preview: {key1: value1, key2: value2, ...}
132
{name: "Alice", age: 30} → "{name: 'Alice', age: 30}"
133

134
// Constructor name for complex objects:
135
new Date() → "Date"
136
/regex/ → "RegExp"
137
function fn() {} → "Function"
138

139
// Primitive values displayed directly:
140
"string" → "string"
141
42 → 42
142
true → true
143
null → null
144
```
145

146
**Usage Examples:**
147

148
```typescript
149
import React from "react";
150
import { ObjectPreview } from "react-inspector";
151

152
function PreviewExamples() {
153
  const complexData = {
154
    users: ["Alice", "Bob"],
155
    config: { debug: true },
156
    timestamp: new Date(),
157
    pattern: /test/gi
158
  };
159
  
160
  return (
161
    <div>
162
      <ObjectPreview data={complexData.users} />
163
      <ObjectPreview data={complexData.config} />
164
      <ObjectPreview data={complexData.timestamp} />
165
      <ObjectPreview data={complexData.pattern} />
166
    </div>
167
  );
168
}
169
```
170

171
### ObjectValue
172

173
Renders values with type-appropriate styling and formatting.
174

175
```typescript { .api }
176
/**
177
 * Renders values with type-appropriate styling
178
 * Handles all JavaScript types with proper formatting and colors
179
 * @param props - ObjectValue rendering props
180
 * @returns React element displaying formatted value
181
 */
182
function ObjectValue(props: ObjectValueProps): React.ReactElement;
183

184
interface ObjectValueProps {
185
  /** Value to render */
186
  object: any;
187
  /** Custom styles to apply */
188
  styles?: React.CSSProperties;
189
}
190
```
191

192
**Type-Specific Rendering:**
193

194
```typescript
195
// Primitives with type-specific colors:
196
"string" → "string" (with quotes, string color)
197
42 → 42 (number color)
198
true → true (boolean color)
199
null → null (null color)
200
undefined → undefined (undefined color)
201
Symbol('sym') → Symbol(sym) (symbol color)
202
123n → 123n (bigint with 'n' suffix)
203

204
// Complex types:
205
function fn() {} → "ƒ fn()" (with function prefix)
206
new Date() → "Mon Jan 01 2024..." (date string)
207
/regex/gi → "/regex/gi" (regex color)
208
[1, 2, 3] → "Array(3)" (array with length)
209
{a: 1} → "Object" (or constructor name)
210
new Map() → "Map" (constructor name)
211
Buffer.from('test') → "Buffer[4]" (buffer with length)
212
```
213

214
**Usage Examples:**
215

216
```typescript
217
import React from "react";
218
import { ObjectValue } from "react-inspector";
219

220
function ValueExamples() {
221
  return (
222
    <div>
223
      <ObjectValue object="Hello World" />
224
      <ObjectValue object={123} />
225
      <ObjectValue object={true} />
226
      <ObjectValue object={null} />
227
      <ObjectValue object={undefined} />
228
      <ObjectValue object={Symbol('test')} />
229
      <ObjectValue object={() => console.log('test')} />
230
      <ObjectValue object={new Date()} />
231
      <ObjectValue object={/pattern/gi} />
232
      <ObjectValue object={[1, 2, 3]} />
233
    </div>
234
  );
235
}
236

237
// With custom styling
238
function StyledValueExample() {
239
  return (
240
    <ObjectValue 
241
      object="Custom styled string"
242
      styles={{ fontSize: '14px', fontWeight: 'bold' }}
243
    />
244
  );
245
}
246
```
247

248
### ObjectName
249

250
Renders property names with optional dimming for non-enumerable properties.
251

252
```typescript { .api }
253
/**
254
 * Renders property names with appropriate styling
255
 * Supports dimming for non-enumerable properties
256
 * @param props - ObjectName rendering props
257
 * @returns React element displaying property name
258
 */
259
function ObjectName(props: ObjectNameProps): React.ReactElement;
260

261
interface ObjectNameProps {
262
  /** Property name to display */
263
  name: string;
264
  /** Whether to dim the name (for non-enumerable properties) */
265
  dimmed?: boolean;
266
  /** Custom styles to apply */
267
  styles?: React.CSSProperties;
268
}
269
```
270

271
**Usage Examples:**
272

273
```typescript
274
import React from "react";
275
import { ObjectName } from "react-inspector";
276

277
function NameExamples() {
278
  return (
279
    <div>
280
      {/* Regular property name */}
281
      <ObjectName name="userName" />
282
      
283
      {/* Dimmed non-enumerable property */}
284
      <ObjectName name="__proto__" dimmed={true} />
285
      
286
      {/* Empty string property name (shows as "") */}
287
      <ObjectName name="" />
288
      
289
      {/* Custom styling */}
290
      <ObjectName 
291
        name="customProperty"
292
        styles={{ color: 'purple', fontStyle: 'italic' }}
293
      />
294
    </div>
295
  );
296
}
297
```
298

299
### Building Custom Node Renderers
300

301
These utility components are commonly used together to build custom node renderers:
302

303
```typescript { .api }
304
/**
305
 * Example custom node renderer using utility components
306
 * @param props - Node renderer props from ObjectInspector
307
 * @returns Custom rendered node
308
 */
309
function customNodeRenderer({ depth, name, data, isNonenumerable }: NodeRendererProps) {
310
  if (depth === 0) {
311
    return <ObjectRootLabel name={name} data={data} />;
312
  }
313
  
314
  // Custom rendering for specific types
315
  if (typeof data === 'function') {
316
    return (
317
      <span>
318
        <ObjectName name={name} dimmed={isNonenumerable} />
319
        <span>: </span>
320
        <ObjectValue object={data} />
321
        <span style={{ color: 'purple' }}> 🔧</span>
322
      </span>
323
    );
324
  }
325
  
326
  // Default rendering
327
  return <ObjectLabel name={name} data={data} isNonenumerable={isNonenumerable} />;
328
}
329
```
330

331
**Complete Custom Inspector Example:**
332

333
```typescript
334
import React from "react";
335
import { 
336
  ObjectInspector, 
337
  ObjectLabel, 
338
  ObjectRootLabel,
339
  ObjectName,
340
  ObjectValue,
341
  ObjectPreview 
342
} from "react-inspector";
343

344
function EnhancedNodeRenderer({ depth, name, data, isNonenumerable }) {
345
  if (depth === 0) {
346
    return (
347
      <div style={{ fontWeight: 'bold', color: 'blue' }}>
348
        <ObjectRootLabel name={name} data={data} />
349
      </div>
350
    );
351
  }
352
  
353
  // Special handling for different data types
354
  const getIcon = (value: any) => {
355
    if (typeof value === 'function') return '⚡';
356
    if (Array.isArray(value)) return '📋';
357
    if (value instanceof Date) return '📅';
358
    if (typeof value === 'string') return '📝';
359
    if (typeof value === 'number') return '🔢';
360
    return '📦';
361
  };
362
  
363
  return (
364
    <span>
365
      <span>{getIcon(data)} </span>
366
      <ObjectName name={name} dimmed={isNonenumerable} />
367
      <span>: </span>
368
      <ObjectValue object={data} />
369
    </span>
370
  );
371
}
372

373
function CustomInspectorExample() {
374
  const data = {
375
    name: "Alice",
376
    age: 30,
377
    hobbies: ["reading", "coding"],
378
    greet: () => "Hello!",
379
    birthday: new Date('1994-06-15')
380
  };
381
  
382
  return (
383
    <ObjectInspector 
384
      data={data}
385
      nodeRenderer={EnhancedNodeRenderer}
386
      expandLevel={1}
387
    />
388
  );
389
}
390
```
391

392
### Integration with Themes
393

394
All utility components respect the current theme and use appropriate theme variables:
395

396
- **ObjectName**: Uses `OBJECT_NAME_COLOR` and dimmed styling
397
- **ObjectValue**: Uses type-specific color variables (`OBJECT_VALUE_STRING_COLOR`, etc.)
398
- **ObjectPreview**: Uses preview-specific styling variables
399
- **ObjectLabel/ObjectRootLabel**: Combine other components' theming
400

401
Custom styles passed via props will override theme defaults.