feat: enhance add_nodes method to support nested children structure

[UmbraCi]

Overview

This PR enhances the add_nodes method to support nested children structures from all major jsMind data formats (node_tree, node_array, and freemind), while maintaining complete backward compatibility.

Key Features

✅ Backward Compatibility

• All existing code using the legacy format continues to work unchanged
• All existing tests pass without modification
• API signature remains the same

🌳 Nested Structure Support

• Supports children arrays with recursive processing
• Handles deep nesting (unlimited levels)
• Processes all child nodes in a single operation

📊 Multiple Format Support

• node_tree format: Native nested object structure
• node_array format: Custom attributes with children
• freemind format: XML-style attributes preserved
• Legacy format: Original format continues to work

⚡ Performance Optimized

• Single UI refresh after all nodes are added
• Batch processing for better performance
• Efficient recursive processing

Usage Examples

Legacy Format (Unchanged)

// This continues to work exactly as before
jm.add_nodes('parent_id', [
    {
        node_id: 'child1',
        topic: 'Child Node 1',
        data: { color: 'red' },
        direction: 'left'
    }
]);

New Nested Format

// Support for nested children
jm.add_nodes('root', [
    {
        id: 'category',
        topic: 'Main Category',
        direction: 'right',
        children: [
            {
                id: 'subcategory1',
                topic: 'Subcategory 1',
                children: [
                    { id: 'item1', topic: 'Item 1' },
                    { id: 'item2', topic: 'Item 2' }
                ]
            }
        ]
    }
]);

Technical Implementation

New Methods Added

• _add_nodes_recursive(parent_node, node_data): Recursively process nodes and children
• _extract_node_tree_subnode(node_data): Extract children from various formats

Format Detection

The method automatically detects the format:

1. Nested Format: If node_data.children exists and is an array
2. Legacy Format: Otherwise, uses original legacy processing
3. Hybrid Support: Can process both formats in the same call

Benefits

For Developers

• Easier Data Import: Directly use data from node_tree, node_array, or freemind formats
• Reduced Code: No need to manually flatten nested structures
• Better Performance: Single operation with batch UI refresh
• Future-Proof: Ready for complex data structures

For Applications

• Rich Data Support: Preserve custom attributes and metadata
• Format Flexibility: Support multiple input formats seamlessly
• Migration Path: Easy upgrade from legacy to nested formats
• Interoperability: Better integration with other mind mapping tools

Testing

The enhancement includes comprehensive tests covering:

• All legacy format scenarios (100% backward compatibility)
• Nested children processing
• Mixed format handling
• Error cases and edge conditions
• Performance with large datasets
• Custom attribute preservation

Files Changed

• src/jsmind.js: Enhanced add_nodes method with nested support
• tests/unit/jsmind.test.js: Comprehensive test coverage
• docs/add_nodes_enhancement.md: Detailed documentation

Migration

No Changes Required

Existing code continues to work without any modifications.

Optional Enhancements

To take advantage of new features, developers can now directly use nested data structures instead of manually flattening them.

This enhancement makes jsMind's add_nodes method significantly more powerful while maintaining complete backward compatibility.

[UmbraCi]

@hizzgdev

[hizzgdev]

加了些评论，麻烦看看。谢谢！

[UmbraCi]

加了些评论，麻烦看看。谢谢！

重构了一下这个方法，因为周末在家是Windows电脑，所以需要加一下cross依赖用来运行script。
另外想问下，开发这个库的时候，我看example中的文件引用的script和css都是cdn的，如果我想一边开发一边调试，你一般是怎么做的呢？ 新建一个demo应用，然后包pnpm link? @hizzgdev

[hizzgdev]

加了些评论，麻烦看看。谢谢！

重构了一下这个方法，因为周末在家是Windows电脑，所以需要加一下cross依赖用来运行script。 另外想问下，开发这个库的时候，我看example中的文件引用的script和css都是cdn的，如果我想一边开发一边调试，你一般是怎么做的呢？ 新建一个demo应用，然后包pnpm link? @hizzgdev

你看 example/demo.html 这里面引用的是 es6 目录里的文件，你在本地用 npm run build 就可以了。它生成的有 map 文件也不影响调试。

[hizzgdev]

麻烦再看看，谢谢！

[UmbraCi]

麻烦再看看，谢谢！

@hizzgdev 重新CR下

[UmbraCi]

麻烦再看看，谢谢！

麻烦再看看，谢谢！

@hizzgdev 麻烦再CR下

[hizzgdev]

再次感谢 @UmbraCi 的支持。
这次的更新挺多，或许还有一些 bug，这个 PR 合并之后，我们需要把这个方法加到文档里，到时候在文档中把它标记为 [实验性], 以提醒用户小心使用。

[UmbraCi]

麻烦再cr下 @hizzgdev