Data Management

/** Primary interface for tree node data */
interface DataNode extends Record<string, any> {
  /** Unique identifier for the node */
  key?: Key;
  /** Value used for selection */
  value?: SafeKey;
  /** Display text or content for the node */
  title?: React.ReactNode;
  /** Child nodes for hierarchical structure */
  children?: DataNode[];
  /** Whether the node is disabled for selection */
  disabled?: boolean;
  /** Whether the checkbox is disabled (in checkable mode) */
  disableCheckbox?: boolean;
  /** Whether the node can be checked (overrides tree-level setting) */
  checkable?: boolean;
  /** Whether the node is a leaf (cannot have children) */
  isLeaf?: boolean;
  /** Icon to display for the node */
  icon?: React.ReactNode;
  /** Additional CSS class name */
  className?: string;
  /** Inline styles for the node */
  style?: React.CSSProperties;
}

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

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

/** Default value type supporting various formats */
type DefaultValueType = SafeKey | LabeledValueType | (SafeKey | LabeledValueType)[];

/** 
 * Interface for customizing field names in tree data
 * Allows integration with existing data structures
 */
interface FieldNames {
  /** Field name for node labels (default: 'title') */
  label?: string;
  /** Field name for node values (default: 'value') */
  value?: string;
  /** Field name for child nodes (default: 'children') */
  children?: string;
}

/**
 * Fills missing field names with defaults
 * @param fieldNames - Partial field names configuration
 * @returns Complete FieldNames with defaults applied
 */
function fillFieldNames(fieldNames?: FieldNames): FieldNames;

// Custom data structure with different field names
const customData = [
  {
    id: "1",
    name: "Root Folder",
    items: [
      { id: "1-1", name: "Subfolder 1", items: [] },
      { id: "1-2", name: "Subfolder 2", items: [] },
    ]
  }
];

// Map custom fields to TreeSelect format
<TreeSelect
  treeData={customData}
  fieldNames={{
    label: 'name',    // Use 'name' field for display
    value: 'id',      // Use 'id' field for values
    children: 'items' // Use 'items' field for children
  }}
/>

// API data with nested structure
const apiData = [
  {
    categoryId: "cat1",
    categoryTitle: "Electronics",
    subcategories: [
      { categoryId: "cat1-1", categoryTitle: "Phones" },
      { categoryId: "cat1-2", categoryTitle: "Laptops" },
    ]
  }
];

<TreeSelect
  treeData={apiData}
  fieldNames={{
    label: 'categoryTitle',
    value: 'categoryId', 
    children: 'subcategories'
  }}
/>

/**
 * Configuration for simple mode data transformation
 * Converts flat array with parent-child relationships into tree structure
 */
interface SimpleModeConfig {
  /** Field name for node ID (default: 'id') */
  id?: string;
  /** Field name for parent ID (default: 'pId') */
  pId?: string;
  /** Value representing root nodes (default: null) */
  rootPId?: string;
}

// Flat data with parent-child relationships
const flatData = [
  { id: "1", pId: null, title: "Root 1" },
  { id: "2", pId: null, title: "Root 2" },
  { id: "1-1", pId: "1", title: "Child 1-1" },
  { id: "1-2", pId: "1", title: "Child 1-2" },
  { id: "1-1-1", pId: "1-1", title: "Grandchild 1-1-1" },
];

// Enable simple mode to auto-convert to tree
<TreeSelect
  treeData={flatData}
  treeDataSimpleMode={{
    id: 'id',
    pId: 'pId',
    rootPId: null
  }}
/>

// Custom field names in simple mode
const customFlatData = [
  { nodeId: "1", parentId: "0", label: "Category 1" },
  { nodeId: "2", parentId: "1", label: "Subcategory 1" },
  { nodeId: "3", parentId: "1", label: "Subcategory 2" },
];

<TreeSelect
  treeData={customFlatData}
  treeDataSimpleMode={{
    id: 'nodeId',
    pId: 'parentId', 
    rootPId: '0'
  }}
  fieldNames={{ label: 'label', value: 'nodeId' }}
/>

/** 
 * Labeled value format for enhanced selection information
 * Used when labelInValue is enabled
 */
interface LabeledValueType {
  /** Node key identifier */
  key?: Key;
  /** Selection value */
  value?: SafeKey;
  /** Display label */
  label?: React.ReactNode;
  /** Whether the node is half-checked (in checkable mode) */
  halfChecked?: boolean;
}

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

/**
 * Checks if a value is null or undefined
 * @param val - Value to check
 * @returns True if null or undefined
 */
function isNil(val: any): boolean;

// Using labelInValue mode
function LabelInValueExample() {
  const [value, setValue] = useState<LabeledValueType[]>([]);
  
  const handleChange = (newValue: LabeledValueType[]) => {
    setValue(newValue);
    // Each value contains: { key, value, label, halfChecked }
    console.log('Selected items:', newValue.map(item => ({
      id: item.value,
      display: item.label,
      isPartial: item.halfChecked
    })));
  };

  return (
    <TreeSelect
      value={value}
      treeData={treeData}
      multiple
      treeCheckable
      labelInValue
      onChange={handleChange}
    />
  );
}

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

/**
 * Checks if a node's checkbox should be disabled
 * @param node - DataNode to check
 * @returns True if checkbox should be disabled
 */
function isCheckDisabled(node: DataNode): boolean;

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

/**
 * Formats selected values according to the specified strategy
 * @param values - Selected values array
 * @param strategy - Display strategy (SHOW_ALL, SHOW_PARENT, SHOW_CHILD)
 * @param keyEntities - Map of key to entity relationships
 * @param fieldNames - Field name mapping
 * @returns Formatted values according to strategy
 */
function formatStrategyValues(
  values: SafeKey[], 
  strategy: CheckedStrategy, 
  keyEntities: Record<SafeKey, any>,
  fieldNames: FieldNames
): SafeKey[];

// Utility usage in custom components
function TreeDataAnalyzer({ treeData, fieldNames }) {
  const allKeys = getAllKeys(treeData, fieldNames);
  const disabledNodes = treeData.filter(isCheckDisabled);
  
  return (
    <div>
      <p>Total nodes: {allKeys.length}</p>
      <p>Disabled nodes: {disabledNodes.length}</p>
    </div>
  );
}

// Custom strategy formatting
function CustomSelectionDisplay({ selectedValues, treeData }) {
  const fieldNames = fillFieldNames(); // Use defaults
  const keyEntities = {}; // Build from treeData
  
  const displayValues = formatStrategyValues(
    selectedValues,
    SHOW_PARENT,
    keyEntities, 
    fieldNames
  );
  
  return <div>Selected: {displayValues.join(', ')}</div>;
}

/** Extended DataNode for legacy compatibility */
interface LegacyDataNode extends DataNode {
  /** Legacy props support */
  props?: any;
}

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

/**
 * Adds legacy properties to data nodes
 * @param dataNode - Node to enhance with legacy props
 */
function fillLegacyProps(dataNode: DataNode): void;

// Core data structures
interface DataNode extends Record<string, any> {
  key?: Key;
  value?: SafeKey; 
  title?: React.ReactNode;
  children?: DataNode[];
  disabled?: boolean;
  disableCheckbox?: boolean;
  checkable?: boolean;
  isLeaf?: boolean;
}

// Configuration interfaces
interface FieldNames {
  label?: string;
  value?: string;
  children?: string;
}

interface SimpleModeConfig {
  id?: string;
  pId?: string;
  rootPId?: string;
}

// Value types
type SafeKey = string | number;
type Key = string | number | null;
type DefaultValueType = SafeKey | LabeledValueType | (SafeKey | LabeledValueType)[];

interface LabeledValueType {
  key?: Key;
  value?: SafeKey;
  label?: React.ReactNode;
  halfChecked?: boolean;
}