0
# Data Management
1

2
Data management utilities and configurations for handling tree data structures, field name mapping, value formatting, and selection state in rc-tree-select.
3

4
## Capabilities
5

6
### Data Types
7

8
Core interfaces and types for representing tree data.
9

10
```typescript { .api }
11
/** Primary interface for tree node data */
12
interface DataNode extends Record<string, any> {
13
  /** Unique identifier for the node */
14
  key?: Key;
15
  /** Value used for selection */
16
  value?: SafeKey;
17
  /** Display text or content for the node */
18
  title?: React.ReactNode;
19
  /** Child nodes for hierarchical structure */
20
  children?: DataNode[];
21
  /** Whether the node is disabled for selection */
22
  disabled?: boolean;
23
  /** Whether the checkbox is disabled (in checkable mode) */
24
  disableCheckbox?: boolean;
25
  /** Whether the node can be checked (overrides tree-level setting) */
26
  checkable?: boolean;
27
  /** Whether the node is a leaf (cannot have children) */
28
  isLeaf?: boolean;
29
  /** Icon to display for the node */
30
  icon?: React.ReactNode;
31
  /** Additional CSS class name */
32
  className?: string;
33
  /** Inline styles for the node */
34
  style?: React.CSSProperties;
35
}
36

37
/** Safe key type for values and identifiers */
38
type SafeKey = string | number;
39

40
/** Extended key type allowing null */
41
type Key = string | number | null;
42

43
/** Default value type supporting various formats */
44
type DefaultValueType = SafeKey | LabeledValueType | (SafeKey | LabeledValueType)[];
45
```
46

47
### Field Name Mapping
48

49
Configuration for mapping custom data structure fields to TreeSelect's expected format.
50

51
```typescript { .api }
52
/** 
53
 * Interface for customizing field names in tree data
54
 * Allows integration with existing data structures
55
 */
56
interface FieldNames {
57
  /** Field name for node labels (default: 'title') */
58
  label?: string;
59
  /** Field name for node values (default: 'value') */
60
  value?: string;
61
  /** Field name for child nodes (default: 'children') */
62
  children?: string;
63
}
64

65
/**
66
 * Fills missing field names with defaults
67
 * @param fieldNames - Partial field names configuration
68
 * @returns Complete FieldNames with defaults applied
69
 */
70
function fillFieldNames(fieldNames?: FieldNames): FieldNames;
71
```
72

73
**Usage Examples:**
74

75
```typescript
76
// Custom data structure with different field names
77
const customData = [
78
  {
79
    id: "1",
80
    name: "Root Folder",
81
    items: [
82
      { id: "1-1", name: "Subfolder 1", items: [] },
83
      { id: "1-2", name: "Subfolder 2", items: [] },
84
    ]
85
  }
86
];
87

88
// Map custom fields to TreeSelect format
89
<TreeSelect
90
  treeData={customData}
91
  fieldNames={{
92
    label: 'name',    // Use 'name' field for display
93
    value: 'id',      // Use 'id' field for values
94
    children: 'items' // Use 'items' field for children
95
  }}
96
/>
97

98
// API data with nested structure
99
const apiData = [
100
  {
101
    categoryId: "cat1",
102
    categoryTitle: "Electronics",
103
    subcategories: [
104
      { categoryId: "cat1-1", categoryTitle: "Phones" },
105
      { categoryId: "cat1-2", categoryTitle: "Laptops" },
106
    ]
107
  }
108
];
109

110
<TreeSelect
111
  treeData={apiData}
112
  fieldNames={{
113
    label: 'categoryTitle',
114
    value: 'categoryId', 
115
    children: 'subcategories'
116
  }}
117
/>
118
```
119

120
### Simple Mode Configuration
121

122
Configuration for converting flat data structures into hierarchical trees.
123

124
```typescript { .api }
125
/**
126
 * Configuration for simple mode data transformation
127
 * Converts flat array with parent-child relationships into tree structure
128
 */
129
interface SimpleModeConfig {
130
  /** Field name for node ID (default: 'id') */
131
  id?: string;
132
  /** Field name for parent ID (default: 'pId') */
133
  pId?: string;
134
  /** Value representing root nodes (default: null) */
135
  rootPId?: string;
136
}
137
```
138

139
**Usage Examples:**
140

141
```typescript
142
// Flat data with parent-child relationships
143
const flatData = [
144
  { id: "1", pId: null, title: "Root 1" },
145
  { id: "2", pId: null, title: "Root 2" },
146
  { id: "1-1", pId: "1", title: "Child 1-1" },
147
  { id: "1-2", pId: "1", title: "Child 1-2" },
148
  { id: "1-1-1", pId: "1-1", title: "Grandchild 1-1-1" },
149
];
150

151
// Enable simple mode to auto-convert to tree
152
<TreeSelect
153
  treeData={flatData}
154
  treeDataSimpleMode={{
155
    id: 'id',
156
    pId: 'pId',
157
    rootPId: null
158
  }}
159
/>
160

161
// Custom field names in simple mode
162
const customFlatData = [
163
  { nodeId: "1", parentId: "0", label: "Category 1" },
164
  { nodeId: "2", parentId: "1", label: "Subcategory 1" },
165
  { nodeId: "3", parentId: "1", label: "Subcategory 2" },
166
];
167

168
<TreeSelect
169
  treeData={customFlatData}
170
  treeDataSimpleMode={{
171
    id: 'nodeId',
172
    pId: 'parentId', 
173
    rootPId: '0'
174
  }}
175
  fieldNames={{ label: 'label', value: 'nodeId' }}
176
/>
177
```
178

179
### Value Types and Formats
180

181
Types for handling different value formats and labeled values.
182

183
```typescript { .api }
184
/** 
185
 * Labeled value format for enhanced selection information
186
 * Used when labelInValue is enabled
187
 */
188
interface LabeledValueType {
189
  /** Node key identifier */
190
  key?: Key;
191
  /** Selection value */
192
  value?: SafeKey;
193
  /** Display label */
194
  label?: React.ReactNode;
195
  /** Whether the node is half-checked (in checkable mode) */
196
  halfChecked?: boolean;
197
}
198

199
/**
200
 * Ensures value is in array format
201
 * @param value - Single value or array of values
202
 * @returns Array containing the value(s)
203
 */
204
function toArray<T>(value: T | T[]): T[];
205

206
/**
207
 * Checks if a value is null or undefined
208
 * @param val - Value to check
209
 * @returns True if null or undefined
210
 */
211
function isNil(val: any): boolean;
212
```
213

214
**Usage Examples:**
215

216
```typescript
217
// Using labelInValue mode
218
function LabelInValueExample() {
219
  const [value, setValue] = useState<LabeledValueType[]>([]);
220
  
221
  const handleChange = (newValue: LabeledValueType[]) => {
222
    setValue(newValue);
223
    // Each value contains: { key, value, label, halfChecked }
224
    console.log('Selected items:', newValue.map(item => ({
225
      id: item.value,
226
      display: item.label,
227
      isPartial: item.halfChecked
228
    })));
229
  };
230

231
  return (
232
    <TreeSelect
233
      value={value}
234
      treeData={treeData}
235
      multiple
236
      treeCheckable
237
      labelInValue
238
      onChange={handleChange}
239
    />
240
  );
241
}
242

243
// Working with utility functions
244
const normalizeValue = (input: string | string[]) => {
245
  const valueArray = toArray(input); // Ensures array format
246
  return valueArray.filter(v => !isNil(v)); // Remove null/undefined
247
};
248
```
249

250
### Tree Data Utilities
251

252
Utility functions for working with tree data structures.
253

254
```typescript { .api }
255
/**
256
 * Checks if a node's checkbox should be disabled
257
 * @param node - DataNode to check
258
 * @returns True if checkbox should be disabled
259
 */
260
function isCheckDisabled(node: DataNode): boolean;
261

262
/**
263
 * Extracts all keys from tree data structure
264
 * @param treeData - Array of tree nodes
265
 * @param fieldNames - Field name mapping configuration
266
 * @returns Array of all node keys in the tree
267
 */
268
function getAllKeys(treeData: DataNode[], fieldNames: FieldNames): SafeKey[];
269

270
/**
271
 * Formats selected values according to the specified strategy
272
 * @param values - Selected values array
273
 * @param strategy - Display strategy (SHOW_ALL, SHOW_PARENT, SHOW_CHILD)
274
 * @param keyEntities - Map of key to entity relationships
275
 * @param fieldNames - Field name mapping
276
 * @returns Formatted values according to strategy
277
 */
278
function formatStrategyValues(
279
  values: SafeKey[], 
280
  strategy: CheckedStrategy, 
281
  keyEntities: Record<SafeKey, any>,
282
  fieldNames: FieldNames
283
): SafeKey[];
284
```
285

286
**Usage Examples:**
287

288
```typescript
289
// Utility usage in custom components
290
function TreeDataAnalyzer({ treeData, fieldNames }) {
291
  const allKeys = getAllKeys(treeData, fieldNames);
292
  const disabledNodes = treeData.filter(isCheckDisabled);
293
  
294
  return (
295
    <div>
296
      <p>Total nodes: {allKeys.length}</p>
297
      <p>Disabled nodes: {disabledNodes.length}</p>
298
    </div>
299
  );
300
}
301

302
// Custom strategy formatting
303
function CustomSelectionDisplay({ selectedValues, treeData }) {
304
  const fieldNames = fillFieldNames(); // Use defaults
305
  const keyEntities = {}; // Build from treeData
306
  
307
  const displayValues = formatStrategyValues(
308
    selectedValues,
309
    SHOW_PARENT,
310
    keyEntities, 
311
    fieldNames
312
  );
313
  
314
  return <div>Selected: {displayValues.join(', ')}</div>;
315
}
316
```
317

318
## Legacy Support
319

320
Types and utilities for backward compatibility.
321

322
```typescript { .api }
323
/** Extended DataNode for legacy compatibility */
324
interface LegacyDataNode extends DataNode {
325
  /** Legacy props support */
326
  props?: any;
327
}
328

329
/**
330
 * Converts TreeNode children to data format
331
 * @param nodes - React TreeNode children
332
 * @returns Array of DataNode objects
333
 */
334
function convertChildrenToData(nodes: React.ReactNode): DataNode[];
335

336
/**
337
 * Adds legacy properties to data nodes
338
 * @param dataNode - Node to enhance with legacy props
339
 */
340
function fillLegacyProps(dataNode: DataNode): void;
341
```
342

343
## Types Summary
344

345
```typescript { .api }
346
// Core data structures
347
interface DataNode extends Record<string, any> {
348
  key?: Key;
349
  value?: SafeKey; 
350
  title?: React.ReactNode;
351
  children?: DataNode[];
352
  disabled?: boolean;
353
  disableCheckbox?: boolean;
354
  checkable?: boolean;
355
  isLeaf?: boolean;
356
}
357

358
// Configuration interfaces
359
interface FieldNames {
360
  label?: string;
361
  value?: string;
362
  children?: string;
363
}
364

365
interface SimpleModeConfig {
366
  id?: string;
367
  pId?: string;
368
  rootPId?: string;
369
}
370

371
// Value types
372
type SafeKey = string | number;
373
type Key = string | number | null;
374
type DefaultValueType = SafeKey | LabeledValueType | (SafeKey | LabeledValueType)[];
375

376
interface LabeledValueType {
377
  key?: Key;
378
  value?: SafeKey;
379
  label?: React.ReactNode;
380
  halfChecked?: boolean;
381
}
382
```