feat(core): add add_nodes API for batch node creation (#667)

* feat(core): add add_nodes API for batch node creation\n\n- Introduce add_nodes method to add multiple nodes efficiently in a single layout pass\n- Update legacy bundle accordingly\n- Add example/test_batch_add.html to demonstrate and benchmark batch addition\n\nRefs: performance optimization for bulk node insertion

* feat: add add_nodes method for batch node creation

- Refactor add_node to use private helper methods _add_node_data and _refresh_node_ui
- Add add_nodes method for optimized batch node creation
- Improve performance by reducing layout calculations from O(n) to O(1)
- Add unit tests for add_nodes functionality
- Remove add_nodes from legacy version as suggested in PR feedback

Addresses feedback from PR #667:
- Split add_node into smaller, reusable methods
- Simplify condition checking in add_nodes
- Focus only on modern ES6 version in src/ directory
- Add comprehensive unit tests

* test: add comprehensive unit tests for add_nodes method

- Add 10 test cases covering various scenarios:
  - Error handling (not editable, parent not found, invalid input)
  - Core functionality (method calls, parameter passing)
  - Event handling and return values
  - Failed node creation scenarios
- Use mocking to avoid DOM-related issues in test environment
- Ensure proper testing of the batch node creation workflow
- All tests pass successfully

* test: enhance add_nodes unit tests with comprehensive coverage

- Add performance test for large-scale node creation (1000 nodes)
- Add complex data structure test with Unicode and multilingual support
- Add comprehensive direction handling test (13 different direction types)
- Refactor create_fake_mind to accept options parameter for better flexibility
- Remove default editable:true from create_fake_mind, require explicit declaration
- Update all test cases to explicitly pass editable:true when needed
- Ensure 100% test pass rate with improved test design and clarity

Performance improvements verified:
- Batch operations call _refresh_node_ui only once (O(1) vs O(n))
- Large node creation completes within 100ms performance threshold
- Complex data structures and Unicode characters handled correctly

Total test coverage: 13 test cases covering error handling, core functionality,
performance optimization, data integrity, and edge cases.

Author: UmbraCi

src/jsmind.js

@@ -414,6 +414,40 @@ export default class jsMind {
         }
         return this.mind.get_node(node);
     }
+    /**
+     * Add node data to the mind map without triggering UI refresh.
+     * @private
+     * @param {import('./jsmind.node.js').Node} parent_node
+     * @param {string} node_id
+     * @param {string} topic
+     * @param {Record<string, any>=} data
+     * @param {('left'|'center'|'right'|'-1'|'0'|'1'|number)=} direction
+     * @returns {import('./jsmind.node.js').Node|null}
+     */
+    _add_node_data(parent_node, node_id, topic, data, direction) {
+        var dir = Direction.of(direction);
+        if (dir === undefined) {
+            dir = this.layout.calculate_next_child_direction(parent_node);
+        }
+        var node = this.mind.add_node(parent_node, node_id, topic, data, dir);
+        if (!!node) {
+            this.view.add_node(node);
+            this.view.reset_node_custom_style(node);
+        }
+        return node;
+    }
+
+    /**
+     * Refresh UI after node changes.
+     * @private
+     * @param {import('./jsmind.node.js').Node} parent_node
+     */
+    _refresh_node_ui(parent_node) {
+        this.layout.layout();
+        this.view.show(false);
+        this.expand_node(parent_node);
+    }
+
     /**
      * Add a new node to the mind map.
      * @param {string | import('./jsmind.node.js').Node} parent_node
@@ -424,30 +458,78 @@ export default class jsMind {
      * @returns {import('./jsmind.node.js').Node|null}
      */
     add_node(parent_node, node_id, topic, data, direction) {
-        if (this.get_editable()) {
-            var the_parent_node = this.get_node(parent_node);
-            var dir = Direction.of(direction);
-            if (dir === undefined) {
-                dir = this.layout.calculate_next_child_direction(the_parent_node);
-            }
-            var node = this.mind.add_node(the_parent_node, node_id, topic, data, dir);
-            if (!!node) {
-                this.view.add_node(node);
-                this.layout.layout();
-                this.view.show(false);
-                this.view.reset_node_custom_style(node);
-                this.expand_node(the_parent_node);
-                this.invoke_event_handle(EventType.edit, {
-                    evt: 'add_node',
-                    data: [the_parent_node.id, node_id, topic, data, dir],
-                    node: node_id,
-                });
-            }
-            return node;
-        } else {
+        if (!this.get_editable()) {
             logger.error('fail, this mind map is not editable');
             return null;
         }
+
+        var the_parent_node = this.get_node(parent_node);
+        if (!the_parent_node) {
+            logger.error('parent node not found');
+            return null;
+        }
+
+        var node = this._add_node_data(the_parent_node, node_id, topic, data, direction);
+        if (!!node) {
+            this._refresh_node_ui(the_parent_node);
+            this.invoke_event_handle(EventType.edit, {
+                evt: 'add_node',
+                data: [the_parent_node.id, node_id, topic, data, Direction.of(direction)],
+                node: node_id,
+            });
+        }
+        return node;
+    }
+
+    /**
+     * Add multiple nodes to the mind map with optimized performance.
+     * @param {string | import('./jsmind.node.js').Node} parent_node - Parent node for all new nodes
+     * @param {Array<{node_id: string, topic: string, data?: Record<string, any>, direction?: ('left'|'center'|'right'|'-1'|'0'|'1'|number)}>} nodes_data - Array of node data objects
+     * @returns {Array<import('./jsmind.node.js').Node|null>} Array of created nodes
+     */
+    add_nodes(parent_node, nodes_data) {
+        if (!this.get_editable()) {
+            logger.error('fail, this mind map is not editable');
+            return [];
+        }
+
+        var the_parent_node = this.get_node(parent_node);
+        if (!the_parent_node) {
+            logger.error('parent node not found');
+            return [];
+        }
+
+        if (!Array.isArray(nodes_data) || nodes_data.length === 0) {
+            logger.warn('nodes_data should be a non-empty array');
+            return [];
+        }
+
+        var created_nodes = [];
+
+        // Batch create node data without triggering UI refresh
+        for (var i = 0; i < nodes_data.length; i++) {
+            var node_data = nodes_data[i];
+            var node = this._add_node_data(
+                the_parent_node,
+                node_data.node_id,
+                node_data.topic,
+                node_data.data,
+                node_data.direction
+            );
+            created_nodes.push(node);
+        }
+
+        // Refresh UI once after all nodes are added
+        if (!!created_nodes.length) {
+            this._refresh_node_ui(the_parent_node);
+            this.invoke_event_handle(EventType.edit, {
+                evt: 'add_nodes',
+                data: [the_parent_node.id, nodes_data],
+                nodes: created_nodes.filter(node => node !== null).map(node => node.id),
+            });
+        }
+
+        return created_nodes;
     }
     /**
      * Insert a node before target node.