@keenmate/svelte-treeview 4.4.0 → 4.5.0

package/dist/ltree/ltree.svelte.js

@@ -4,7 +4,8 @@ import { isEmptyString } from '../helpers/string-helpers.js';
 import { getLevel, getParentPath, getPathSegments, getRelativePath } from '../helpers/ltree-helpers.js';
 import { createSearchIndex } from './flex.js';
 import { Indexer } from './indexer.js';
-export function createLTree(_idMember, _pathMember, _parentPathMember, _levelMember, _hasChildrenMember, _isExpandedMember, _isSelectableMember, _isDraggableMember, _isDropAllowedMember, _displayValueMember, _getDisplayValueCallback, _searchValueMember, _getSearchValueCallback, _treeId, _treePathSeparator, _expandLevel, _shouldUseInternalSearchIndex, _initializeIndexCallback, _indexerBatchSize, _indexerTimeout, opts) {
+import { perfStart, perfEnd, perfSummary } from '../perf-logger.js';
+export function createLTree(_idMember, _pathMember, _parentPathMember, _levelMember, _hasChildrenMember, _isExpandedMember, _isSelectableMember, _isDraggableMember, _isDropAllowedMember, _displayValueMember, _getDisplayValueCallback, _searchValueMember, _getSearchValueCallback, _orderMember, _treeId, _treePathSeparator, _expandLevel, _shouldUseInternalSearchIndex, _initializeIndexCallback, _indexerBatchSize, _indexerTimeout, opts) {
     let shouldCalculateParentPath = isEmptyString(_parentPathMember);
     let shouldCalculateLevel = isEmptyString(_levelMember);
     let shouldCalculateHasChildren = isEmptyString(_hasChildrenMember);
@@ -58,6 +59,7 @@ export function createLTree(_idMember, _pathMember, _parentPathMember, _levelMem
         getDisplayValueCallback: _getDisplayValueCallback,
         searchValueMember: _searchValueMember,
         getSearchValueCallback: _getSearchValueCallback,
+        orderMember: _orderMember,
         isSorted: false,
         // Properties for filtering
         filteredTree,
@@ -88,7 +90,11 @@ export function createLTree(_idMember, _pathMember, _parentPathMember, _levelMem
             // Clear any pending indexing from previous calls
             indexer?.clearQueue();
             flatTreeNodes = [];
-            performance.mark('conversion-start');
+            // Clear existing tree data - reset root children
+            root.children = {};
+            nodeCount = 0;
+            maxLevel = 0;
+            perfStart(`[${_treeId}] insertArray:conversion`);
             let mappedData = data.map((row, index) => {
                 const node = createLTreeNode();
                 node.treeId = _treeId;
@@ -119,10 +125,10 @@ export function createLTree(_idMember, _pathMember, _parentPathMember, _levelMem
                 node.data = row;
                 return node;
             });
-            performance.mark('conversion-end');
+            const conversionTime = perfEnd(`[${_treeId}] insertArray:conversion`, data.length);
             if (this.shouldDisplayDebugInformation)
                 console.log(`[Tree ${_treeId}] Mapped data before sort`, mappedData);
-            performance.mark('sort-start');
+            perfStart(`[${_treeId}] insertArray:sort`);
             if (!this.isSorted) {
                 if (this.sortCallback)
                     mappedData = this.sortCallback(mappedData);
@@ -131,13 +137,24 @@ export function createLTree(_idMember, _pathMember, _parentPathMember, _levelMem
             }
             if (this.shouldDisplayDebugInformation)
                 console.log(`[Tree ${_treeId}] Mapped data after sort`, mappedData);
-            performance.mark('sort-end');
-            performance.mark('insert-start');
+            const sortTime = perfEnd(`[${_treeId}] insertArray:sort`, data.length);
+            perfStart(`[${_treeId}] insertArray:insert`);
             const failedNodes = [];
             const itemsToIndex = [];
             let realIndex = 0; // this is used to avoid scenario, when node cannot found a parent
             let successfulCount = 0;
             let hasRenderedExpandLevel = false;
+            // Pre-compute the last index at expandLevel to avoid O(n²) lookup
+            let lastExpandLevelIndex = -1;
+            if (_expandLevel && !noEmitChanges) {
+                for (let i = mappedData.length - 1; i >= 0; i--) {
+                    const nodeLevel = mappedData[i].level || getLevel(mappedData[i].path, this.treePathSeparator);
+                    if (nodeLevel <= _expandLevel) {
+                        lastExpandLevelIndex = i;
+                        break;
+                    }
+                }
+            }
             mappedData.forEach((node, index) => {
                 const result = this.insertTreeNode(node.parentPath, node, true);
                 if (result) {
@@ -156,20 +173,12 @@ export function createLTree(_idMember, _pathMember, _parentPathMember, _levelMem
                         realIndex++;
                     }
                     // Progressive rendering: emit changes when we complete expandLevel
-                    if (!noEmitChanges && !hasRenderedExpandLevel && _expandLevel && node.level && node.level <= _expandLevel) {
-                        // Check if this might be the last node at expandLevel by looking ahead
-                        const remainingNodes = mappedData.slice(index + 1);
-                        const hasMoreAtExpandLevel = remainingNodes.some(futureNode => {
-                            const futureLevel = futureNode.level || getLevel(futureNode.path, this.treePathSeparator);
-                            return futureLevel <= _expandLevel;
-                        });
-                        if (!hasMoreAtExpandLevel) {
-                            // We've processed all nodes up to expandLevel - render now!
-                            hasRenderedExpandLevel = true;
-                            this._emitTreeChanged();
-                            if (this.shouldDisplayDebugInformation) {
-                                console.log(`[Tree ${_treeId}] Progressive render: Displayed levels 1-${_expandLevel} (${successfulCount} nodes processed so far)`);
-                            }
+                    if (!noEmitChanges && !hasRenderedExpandLevel && _expandLevel && index === lastExpandLevelIndex) {
+                        // We've processed all nodes up to expandLevel - render now!
+                        hasRenderedExpandLevel = true;
+                        this._emitTreeChanged();
+                        if (this.shouldDisplayDebugInformation) {
+                            console.log(`[Tree ${_treeId}] Progressive render: Displayed levels 1-${_expandLevel} (${successfulCount} nodes processed so far)`);
                         }
                     }
                 }
@@ -207,16 +216,13 @@ export function createLTree(_idMember, _pathMember, _parentPathMember, _levelMem
                     }
                 }
             }
-            performance.mark('insert-end');
-            performance.measure('sort-duration', 'sort-start', 'sort-end');
-            performance.measure('conversion-duration', 'conversion-start', 'conversion-end');
-            performance.measure('insert-duration', 'insert-start', 'insert-end');
-            let measure = performance.getEntriesByName('sort-duration')[0];
-            console.log(`[Tree ${_treeId}] Sort took: ${measure.duration}ms`);
-            measure = performance.getEntriesByName('conversion-duration')[0];
-            console.log(`[Tree ${_treeId}] Conversion took: ${measure.duration}ms`);
-            measure = performance.getEntriesByName('insert-duration')[0];
-            console.log(`[Tree ${_treeId}] Insert took: ${measure.duration}ms`);
+            const insertTime = perfEnd(`[${_treeId}] insertArray:insert`, data.length);
+            // Log performance summary
+            perfSummary(_treeId, {
+                'Conversion': conversionTime,
+                'Sort': sortTime,
+                'Insert': insertTime
+            }, data.length);
             return {
                 successful: successfulCount,
                 failed: failedNodes,
@@ -263,8 +269,10 @@ export function createLTree(_idMember, _pathMember, _parentPathMember, _levelMem
                     console.warn(`[Tree ${_treeId}] Internal search index is disabled`);
                 return;
             }
+            perfStart(`[${_treeId}] filterNodes:search`);
             const resultIndices = searchIndex.search(_searchText, _searchOptions);
             const foundPaths = resultIndices.map((row) => flatTreeNodes[row].path);
+            perfEnd(`[${_treeId}] filterNodes:search`, resultIndices.length);
             if (this.shouldDisplayDebugInformation)
                 console.warn(`[Tree ${_treeId}] Found indices:`, resultIndices, foundPaths);
             this.createFilteredTree(foundPaths);
@@ -287,6 +295,7 @@ export function createLTree(_idMember, _pathMember, _parentPathMember, _levelMem
             return foundNodes;
         },
         createFilteredTree(targetPaths) {
+            perfStart(`[${_treeId}] createFilteredTree`);
             filteredRoot.children = {};
             filteredTree = null;
             // isFiltered = false;
@@ -350,6 +359,7 @@ export function createLTree(_idMember, _pathMember, _parentPathMember, _levelMem
             filteredTree = rootNodes;
             this.isFiltered = true;
             this._emitTreeChanged();
+            perfEnd(`[${_treeId}] createFilteredTree`, rootNodes.length);
             if (this.shouldDisplayDebugInformation)
                 console.log(`[Tree ${_treeId}] Created filtered tree with`, rootNodes.length, 'root nodes');
         },
@@ -360,18 +370,22 @@ export function createLTree(_idMember, _pathMember, _parentPathMember, _levelMem
             this._emitTreeChanged();
         },
         expandAll(nodePath) {
+            perfStart(`[${_treeId}] expandAll`);
             if (isEmptyString(nodePath))
                 flatTreeNodes.forEach((row) => {
                     row.isExpanded = true;
                 });
             this._emitTreeChanged();
+            perfEnd(`[${_treeId}] expandAll`, flatTreeNodes.length);
         },
         collapseAll(nodePath) {
+            perfStart(`[${_treeId}] collapseAll`);
             if (isEmptyString(nodePath))
                 flatTreeNodes.forEach((row) => {
                     row.isExpanded = false;
                 });
             this._emitTreeChanged();
+            perfEnd(`[${_treeId}] collapseAll`, flatTreeNodes.length);
         },
         insert: function (path, data, noEmitChanges = false) {
             let node = this.root;
@@ -455,6 +469,547 @@ export function createLTree(_idMember, _pathMember, _parentPathMember, _levelMem
         refresh() {
             this._emitTreeChanged();
         },
+        /**
+         * Get direct children of a node at the given path
+         * @param parentPath - Path to parent node (empty string for root)
+         * @returns Array of child nodes
+         */
+        getChildren(parentPath) {
+            const parent = this.getNodeByPath(parentPath);
+            if (!parent)
+                return [];
+            return Object.values(parent.children);
+        },
+        /**
+         * Get siblings of a node (including the node itself)
+         * @param path - Path to the node
+         * @returns Array of sibling nodes (nodes with same parent)
+         */
+        getSiblings(path) {
+            const node = this.getNodeByPath(path);
+            if (!node)
+                return [];
+            // Get parent and return all its children
+            const parentPath = node.parentPath || '';
+            return this.getChildren(parentPath);
+        },
+        /**
+         * Re-sort siblings under a parent path using sortCallback or default sort
+         * This reorders the children object to reflect updated order values
+         * @param parentPath - Path to parent node (empty string for root)
+         */
+        refreshSiblings(parentPath) {
+            const parent = parentPath ? this.getNodeByPath(parentPath) : root;
+            if (!parent)
+                return;
+            // Get current children as array
+            const children = Object.values(parent.children);
+            if (children.length === 0)
+                return;
+            // Sort using sortCallback or default sort
+            let sorted;
+            if (this.sortCallback) {
+                sorted = this.sortCallback(children);
+            }
+            else {
+                // Use a simplified sort for siblings only (all same level/parent)
+                sorted = [...children].sort((a, b) => {
+                    // If orderMember is provided, use it
+                    if (this.orderMember && a.data && b.data) {
+                        const aOrder = a.data[this.orderMember] ?? 0;
+                        const bOrder = b.data[this.orderMember] ?? 0;
+                        if (aOrder !== bOrder) {
+                            return aOrder - bOrder;
+                        }
+                    }
+                    // Fall back to display value
+                    return this.getNodeDisplayValue(a).localeCompare(this.getNodeDisplayValue(b));
+                });
+            }
+            // Rebuild children object in sorted order
+            const newChildren = {};
+            sorted.forEach(child => {
+                const segment = segmentPrefix + child.pathSegment;
+                newChildren[segment] = child;
+            });
+            parent.children = newChildren;
+            if (this.shouldDisplayDebugInformation) {
+                console.log(`[Tree ${_treeId}] refreshSiblings: Re-sorted ${sorted.length} children under "${parentPath || 'root'}":`, sorted.map(s => ({ path: s.path, sortOrder: s.data?.[this.orderMember] })));
+            }
+            this._emitTreeChanged();
+        },
+        /**
+         * Refresh a single node and optionally its descendants
+         * Useful after modifying node data externally
+         * @param path - Path to the node to refresh
+         */
+        refreshNode(path) {
+            // For now, just trigger a tree change
+            // Future optimization: only re-render the specific subtree
+            this._emitTreeChanged();
+        },
+        /**
+         * Move a node to a new location in the tree
+         * @param sourcePath - Path of the node to move
+         * @param targetPath - Path of the target node
+         * @param position - Where to place relative to target: 'above', 'below', or 'child'
+         * @returns Object with success status and optional error message
+         */
+        moveNode(sourcePath, targetPath, position) {
+            // Find source node
+            const sourceNode = this.getNodeByPath(sourcePath);
+            if (!sourceNode) {
+                return { success: false, error: `Source node not found: ${sourcePath}` };
+            }
+            // Find target node
+            const targetNode = this.getNodeByPath(targetPath);
+            if (!targetNode) {
+                return { success: false, error: `Target node not found: ${targetPath}` };
+            }
+            // Prevent moving a node into itself or its descendants
+            if (targetPath.startsWith(sourcePath + this.treePathSeparator) || targetPath === sourcePath) {
+                return { success: false, error: 'Cannot move a node into itself or its descendants' };
+            }
+            // Get source's current parent
+            const sourceParentPath = sourceNode.parentPath || '';
+            const sourceParent = sourceParentPath ? this.getNodeByPath(sourceParentPath) : root;
+            if (!sourceParent) {
+                return { success: false, error: `Source parent not found: ${sourceParentPath}` };
+            }
+            // Remove source from current parent
+            const sourceSegment = segmentPrefix + sourceNode.pathSegment;
+            delete sourceParent.children[sourceSegment];
+            // Update source parent's hasChildren
+            if (Object.keys(sourceParent.children).length === 0) {
+                sourceParent.hasChildren = false;
+            }
+            // Calculate new parent and path
+            let newParentPath;
+            let newParent;
+            if (position === 'child') {
+                // Insert as child of target
+                newParentPath = targetPath;
+                newParent = targetNode;
+            }
+            else {
+                // Insert as sibling (above or below)
+                newParentPath = targetNode.parentPath || '';
+                newParent = newParentPath ? this.getNodeByPath(newParentPath) : root;
+            }
+            // Generate new path segment (use source's original segment if unique)
+            let newSegment = sourceNode.pathSegment;
+            // Check if a node with this segment already exists in the new parent (excluding source node itself)
+            const existingChild = newParent.children[segmentPrefix + newSegment];
+            if (existingChild && existingChild !== sourceNode) {
+                // Segment collision - generate a unique segment
+                // Try using the source's ID first, then fall back to timestamp
+                const sourceId = sourceNode.id?.toString();
+                if (sourceId && !newParent.children[segmentPrefix + sourceId]) {
+                    newSegment = sourceId;
+                }
+                else {
+                    // Generate unique segment with timestamp
+                    newSegment = `${newSegment}_${Date.now()}`;
+                }
+            }
+            const newPath = newParentPath ? `${newParentPath}${this.treePathSeparator}${newSegment}` : newSegment;
+            // Update source node's path and parentPath
+            const oldPath = sourceNode.path;
+            sourceNode.path = newPath;
+            sourceNode.pathSegment = newSegment;
+            sourceNode.parentPath = newParentPath || null;
+            sourceNode.level = getLevel(newPath, this.treePathSeparator);
+            // Update the data object's path if pathMember is defined
+            if (this.pathMember && sourceNode.data) {
+                sourceNode.data[this.pathMember] = newPath;
+            }
+            // Update all descendants' paths recursively
+            this._updateDescendantPaths(sourceNode, oldPath, newPath);
+            // Insert into new parent
+            newParent.children[segmentPrefix + newSegment] = sourceNode;
+            newParent.hasChildren = true;
+            // If orderMember is defined and position is above/below, calculate order
+            if (this.orderMember && position !== 'child' && sourceNode.data) {
+                const siblings = Object.values(newParent.children);
+                const targetOrder = targetNode.data?.[this.orderMember] ?? 0;
+                if (position === 'above') {
+                    // Find order value just below target
+                    const siblingOrders = siblings
+                        .filter(s => s !== sourceNode && s.data?.[this.orderMember] !== undefined)
+                        .map(s => s.data[this.orderMember])
+                        .filter(o => o < targetOrder)
+                        .sort((a, b) => b - a);
+                    const belowOrder = siblingOrders[0] ?? targetOrder - 20;
+                    sourceNode.data[this.orderMember] = Math.floor((belowOrder + targetOrder) / 2);
+                }
+                else {
+                    // Find order value just above target
+                    const siblingOrders = siblings
+                        .filter(s => s !== sourceNode && s.data?.[this.orderMember] !== undefined)
+                        .map(s => s.data[this.orderMember])
+                        .filter(o => o > targetOrder)
+                        .sort((a, b) => a - b);
+                    const aboveOrder = siblingOrders[0] ?? targetOrder + 20;
+                    sourceNode.data[this.orderMember] = Math.floor((targetOrder + aboveOrder) / 2);
+                }
+            }
+            // Re-sort siblings if needed
+            this.refreshSiblings(newParentPath);
+            return { success: true };
+        },
+        /**
+         * Helper to recursively update descendant paths after a move
+         */
+        _updateDescendantPaths(node, oldBasePath, newBasePath) {
+            for (const child of Object.values(node.children)) {
+                // Save the old path BEFORE updating, for correct recursive calculation
+                const oldChildPath = child.path;
+                // Calculate new path by replacing the old base with new base
+                const relativePath = oldChildPath.substring(oldBasePath.length);
+                const newChildPath = newBasePath + relativePath;
+                child.path = newChildPath;
+                child.parentPath = node.path;
+                child.level = getLevel(newChildPath, this.treePathSeparator);
+                // Update the data object's path if pathMember is defined
+                if (this.pathMember && child.data) {
+                    child.data[this.pathMember] = newChildPath;
+                }
+                // Recurse into children using the OLD child path as base
+                this._updateDescendantPaths(child, oldChildPath, newChildPath);
+            }
+        },
+        /**
+         * Remove a node from the tree
+         * @param path - Path of the node to remove
+         * @param includeDescendants - If true, removes all descendants (default: true)
+         * @returns Object with success status and the removed node
+         */
+        removeNode(path, includeDescendants = true) {
+            const node = this.getNodeByPath(path);
+            if (!node) {
+                return { success: false, error: `Node not found: ${path}` };
+            }
+            // Get parent
+            const parentPath = node.parentPath || '';
+            const parent = parentPath ? this.getNodeByPath(parentPath) : root;
+            if (!parent) {
+                return { success: false, error: `Parent not found: ${parentPath}` };
+            }
+            // Remove from parent
+            const segment = segmentPrefix + node.pathSegment;
+            delete parent.children[segment];
+            // Update parent's hasChildren
+            if (Object.keys(parent.children).length === 0) {
+                parent.hasChildren = false;
+            }
+            // Update node count
+            if (includeDescendants) {
+                const countDescendants = (n) => {
+                    let count = 1;
+                    for (const child of Object.values(n.children)) {
+                        count += countDescendants(child);
+                    }
+                    return count;
+                };
+                nodeCount -= countDescendants(node);
+            }
+            else {
+                nodeCount--;
+            }
+            this._emitTreeChanged();
+            return { success: true, node };
+        },
+        /**
+         * Add a new node to the tree
+         * @param parentPath - Path of the parent (empty string for root)
+         * @param data - The data object for the new node
+         * @param pathSegment - Optional path segment (auto-generated if not provided)
+         * @returns Object with success status and the created node
+         */
+        addNode(parentPath, data, pathSegment) {
+            const parent = parentPath ? this.getNodeByPath(parentPath) : root;
+            if (!parent && parentPath) {
+                return { success: false, error: `Parent not found: ${parentPath}` };
+            }
+            // Generate path segment if not provided
+            if (!pathSegment) {
+                // Use ID from data if available, otherwise generate a unique one
+                const id = _idMember && data ? data[_idMember] : undefined;
+                pathSegment = id?.toString() || `new_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+            }
+            // Calculate full path
+            const newPath = parentPath ? `${parentPath}${this.treePathSeparator}${pathSegment}` : pathSegment;
+            // Check if path already exists
+            if (this.getNodeByPath(newPath)) {
+                return { success: false, error: `Node already exists at path: ${newPath}` };
+            }
+            // Create the node
+            const newNode = createLTreeNode();
+            newNode.treeId = _treeId;
+            newNode.id = _idMember && data ? data[_idMember] : undefined;
+            newNode.path = newPath;
+            newNode.pathSegment = pathSegment;
+            newNode.parentPath = parentPath || null;
+            newNode.level = getLevel(newPath, this.treePathSeparator);
+            newNode.data = data;
+            newNode.isExpanded = _expandLevel ? newNode.level <= _expandLevel : false;
+            newNode.hasChildren = false;
+            // Update path in data if pathMember is defined
+            if (_pathMember && data) {
+                data[_pathMember] = newPath;
+            }
+            // Add to parent
+            const targetParent = parent || root;
+            targetParent.children[segmentPrefix + pathSegment] = newNode;
+            targetParent.hasChildren = true;
+            // Update statistics
+            nodeCount++;
+            maxLevel = Math.max(maxLevel, newNode.level || 0);
+            // Add to flat tree for search indexing
+            flatTreeNodes.push(newNode);
+            // Re-sort siblings to place new node in correct position
+            this.refreshSiblings(parentPath);
+            if (this.shouldDisplayDebugInformation) {
+                const siblings = Object.values(targetParent.children);
+                console.log(`[Tree ${_treeId}] addNode: Added "${newPath}" to "${parentPath || 'root'}". Siblings after sort:`, siblings.map(s => ({ path: s.path, sortOrder: s.data?.[this.orderMember] })));
+            }
+            this._emitTreeChanged();
+            return { success: true, node: newNode };
+        },
+        /**
+         * Update an existing node's data
+         * @param path - Path of the node to update
+         * @param dataUpdates - Partial data to merge into existing node data
+         * @returns Object with success status and the updated node
+         */
+        updateNode(path, dataUpdates) {
+            const node = this.getNodeByPath(path);
+            if (!node) {
+                return { success: false, error: `Node not found: ${path}` };
+            }
+            if (!node.data) {
+                return { success: false, error: `Node has no data: ${path}` };
+            }
+            // Check if orderMember is being updated (will need re-sort)
+            const orderMemberUpdated = this.orderMember && this.orderMember in dataUpdates;
+            if (this.shouldDisplayDebugInformation) {
+                console.log(`[Tree ${_treeId}] updateNode: "${path}" updating:`, dataUpdates);
+            }
+            // Merge updates into existing data
+            node.data = { ...node.data, ...dataUpdates };
+            // Re-index for search if needed
+            if (indexer && _shouldUseInternalSearchIndex) {
+                const flatIndex = flatTreeNodes.indexOf(node);
+                if (flatIndex !== -1) {
+                    indexer.addItem({ node, index: flatIndex });
+                }
+            }
+            // Re-sort siblings if order was updated
+            if (orderMemberUpdated) {
+                this.refreshSiblings(node.parentPath || '');
+            }
+            this._emitTreeChanged();
+            return { success: true, node };
+        },
+        /**
+         * Apply multiple changes to the tree in a single batch
+         * @param changes - Array of create/update/delete operations
+         * @returns Object with count of successful operations and array of failures
+         */
+        applyChanges(changes) {
+            const failures = [];
+            let successCount = 0;
+            for (let i = 0; i < changes.length; i++) {
+                const change = changes[i];
+                let result;
+                switch (change.operation) {
+                    case 'create':
+                        result = this.addNode(change.parentPath, change.data, change.pathSegment);
+                        if (result.success) {
+                            successCount++;
+                        }
+                        else {
+                            failures.push({
+                                index: i,
+                                operation: change.operation,
+                                path: change.parentPath,
+                                error: result.error || 'Unknown error'
+                            });
+                        }
+                        break;
+                    case 'update':
+                        result = this.updateNode(change.path, change.data);
+                        if (result.success) {
+                            successCount++;
+                        }
+                        else {
+                            failures.push({
+                                index: i,
+                                operation: change.operation,
+                                path: change.path,
+                                error: result.error || 'Unknown error'
+                            });
+                        }
+                        break;
+                    case 'delete':
+                        result = this.removeNode(change.path);
+                        if (result.success) {
+                            successCount++;
+                        }
+                        else {
+                            failures.push({
+                                index: i,
+                                operation: change.operation,
+                                path: change.path,
+                                error: result.error || 'Unknown error'
+                            });
+                        }
+                        break;
+                }
+            }
+            // Single emission after all changes
+            if (successCount > 0) {
+                this._emitTreeChanged();
+            }
+            return { successful: successCount, failed: failures };
+        },
+        /**
+         * Copy a node and all its descendants to a new location
+         * Useful for cross-tree drag-drop operations
+         * @param sourceNode - The node to copy (including its children)
+         * @param targetParentPath - Path where to insert the copy (empty string for root)
+         * @param transformData - Function to transform each node's data (e.g., assign new IDs)
+         * @param siblingPath - Optional path of sibling to position relative to
+         * @param position - Optional position relative to sibling ('above' or 'below')
+         * @returns Object with success status, the created root node, and count of nodes created
+         */
+        copyNodeWithDescendants(sourceNode, targetParentPath, transformData, siblingPath, position) {
+            if (!sourceNode.data) {
+                return { success: false, count: 0, error: 'Source node has no data' };
+            }
+            let totalCount = 0;
+            // Recursive helper function
+            const copyRecursive = (node, parentPath) => {
+                if (!node.data)
+                    return null;
+                // Transform the data (user assigns new IDs, etc.)
+                const transformedData = transformData(node.data);
+                // Add the node
+                const result = this.addNode(parentPath, transformedData);
+                if (!result.success || !result.node) {
+                    if (this.shouldDisplayDebugInformation) {
+                        console.warn(`[Tree ${_treeId}] copyNodeWithDescendants: Failed to add node`, result.error);
+                    }
+                    return null;
+                }
+                totalCount++;
+                const newNode = result.node;
+                // Recursively copy children
+                if (node.children && Object.keys(node.children).length > 0) {
+                    for (const child of Object.values(node.children)) {
+                        copyRecursive(child, newNode.path);
+                    }
+                }
+                return newNode;
+            };
+            // Start the recursive copy
+            const rootNode = copyRecursive(sourceNode, targetParentPath);
+            if (!rootNode) {
+                return { success: false, count: 0, error: 'Failed to copy root node' };
+            }
+            // Handle positioning relative to sibling if specified
+            if (siblingPath && position && rootNode.data) {
+                const siblingNode = this.getNodeByPath(siblingPath);
+                if (siblingNode && this.orderMember) {
+                    // Get the parent to access siblings
+                    const parent = targetParentPath ? this.getNodeByPath(targetParentPath) : root;
+                    if (parent) {
+                        const siblings = Object.values(parent.children);
+                        const siblingOrder = siblingNode.data?.[this.orderMember] ?? 0;
+                        if (position === 'above') {
+                            // Find order value just below sibling
+                            const siblingOrders = siblings
+                                .filter(s => s !== rootNode && s.data?.[this.orderMember] !== undefined)
+                                .map(s => s.data[this.orderMember])
+                                .filter(o => o < siblingOrder)
+                                .sort((a, b) => b - a);
+                            const belowOrder = siblingOrders[0] ?? siblingOrder - 20;
+                            rootNode.data[this.orderMember] = Math.floor((belowOrder + siblingOrder) / 2);
+                        }
+                        else {
+                            // Find order value just above sibling
+                            const siblingOrders = siblings
+                                .filter(s => s !== rootNode && s.data?.[this.orderMember] !== undefined)
+                                .map(s => s.data[this.orderMember])
+                                .filter(o => o > siblingOrder)
+                                .sort((a, b) => a - b);
+                            const aboveOrder = siblingOrders[0] ?? siblingOrder + 20;
+                            rootNode.data[this.orderMember] = Math.floor((siblingOrder + aboveOrder) / 2);
+                        }
+                        // Re-sort siblings
+                        this.refreshSiblings(targetParentPath);
+                    }
+                }
+            }
+            if (this.shouldDisplayDebugInformation) {
+                console.log(`[Tree ${_treeId}] copyNodeWithDescendants: Copied ${totalCount} nodes to "${targetParentPath}"${siblingPath ? ` ${position} "${siblingPath}"` : ''}`);
+            }
+            return { success: true, rootNode, count: totalCount };
+        },
+        /**
+         * Get paths of all expanded nodes
+         * Useful for saving expanded state before a full redraw
+         * @returns Array of paths that are currently expanded
+         */
+        getExpandedPaths() {
+            const paths = [];
+            const traverse = (node) => {
+                if (node.isExpanded && node.path) {
+                    paths.push(node.path);
+                }
+                for (const child of Object.values(node.children)) {
+                    traverse(child);
+                }
+            };
+            traverse(root);
+            return paths;
+        },
+        /**
+         * Set expanded state for given paths
+         * Useful for restoring expanded state after a full redraw
+         * @param paths - Array of paths to expand (all others will be collapsed)
+         */
+        setExpandedPaths(paths) {
+            const pathSet = new Set(paths);
+            const traverse = (node) => {
+                if (node.path) {
+                    node.isExpanded = pathSet.has(node.path);
+                }
+                for (const child of Object.values(node.children)) {
+                    traverse(child);
+                }
+            };
+            traverse(root);
+            this._emitTreeChanged();
+        },
+        /**
+         * Extract all node data as a flat array
+         * Useful for saving the entire tree state to a database
+         * @returns Array of all node data objects
+         */
+        getAllData() {
+            const result = [];
+            const traverse = (node) => {
+                if (node.data) {
+                    result.push(node.data);
+                }
+                for (const child of Object.values(node.children)) {
+                    traverse(child);
+                }
+            };
+            traverse(root);
+            return result;
+        },
         _defaultSort: function (self, items) {
             return items.sort((a, b) => {
                 // First, sort by level (shallower levels first)
@@ -471,6 +1026,14 @@ export function createLTree(_idMember, _pathMember, _parentPathMember, _levelMem
                         return 1;
                     return a.parentPath.localeCompare(b.parentPath);
                 }
+                // If orderMember is provided, use it for sibling ordering
+                if (self.orderMember && a.data && b.data) {
+                    const aOrder = a.data[self.orderMember] ?? 0;
+                    const bOrder = b.data[self.orderMember] ?? 0;
+                    if (aOrder !== bOrder) {
+                        return aOrder - bOrder;
+                    }
+                }
                 // Finally sort by display value
                 return self.getNodeDisplayValue(a).localeCompare(self.getNodeDisplayValue(b));
             });