@keenmate/svelte-treeview 4.5.0 → 4.6.0

package/dist/components/Tree.svelte.d.ts

@@ -45,11 +45,22 @@ declare function $$render<T>(): {
         shouldDisplayContextMenuInDebugMode?: boolean;
         isLoading?: boolean;
         progressiveRender?: boolean;
-        renderBatchSize?: number;
+        initialBatchSize?: number;
+        maxBatchSize?: number;
         isRendering?: boolean;
         onRenderStart?: () => void;
         onRenderProgress?: (stats: RenderStats) => void;
         onRenderComplete?: (stats: RenderStats) => void;
+        /**
+         * Use flat/centralized rendering instead of recursive node rendering.
+         * This significantly improves performance for large trees by:
+         * - Removing the {#key changeTracker} block that destroys all nodes on any change
+         * - Using a single flat loop instead of recursive component instantiation
+         * - Allowing Svelte's keyed {#each} to efficiently diff only changed nodes
+         */
+        useFlatRendering?: boolean;
+        /** Indentation per level in flat rendering mode (CSS value, default: '1.5rem') */
+        flatIndentSize?: string;
         dragDropMode?: DragDropMode;
         dropZoneMode?: "floating" | "glow";
         dropZoneLayout?: "around" | "above" | "below" | "wave" | "wave2";
@@ -64,11 +75,15 @@ declare function $$render<T>(): {
          * Called before a drop is processed. Return false to cancel the drop.
          * Return { position, operation } to override the drop position or operation.
          * Return true or undefined to proceed normally.
+         * Can be async - return a Promise to show dialogs or perform async validation.
          */
         beforeDropCallback?: (dropNode: LTreeNode<T> | null, draggedNode: LTreeNode<T>, position: DropPosition, event: DragEvent | TouchEvent, operation: DropOperation) => boolean | {
             position?: DropPosition;
             operation?: DropOperation;
-        } | void;
+        } | void | Promise<boolean | {
+            position?: DropPosition;
+            operation?: DropOperation;
+        } | void>;
         onNodeDrop?: (dropNode: LTreeNode<T> | null, draggedNode: LTreeNode<T>, position: DropPosition, event: DragEvent | TouchEvent, operation: DropOperation) => void;
         contextMenuCallback?: (node: LTreeNode<T>, closeMenuCallback: () => void) => ContextMenuItem[];
         bodyClass?: string | null | undefined;
@@ -125,7 +140,10 @@ declare function $$render<T>(): {
         getAllData: () => T[];
         closeContextMenu: () => void;
         scrollToPath: (path: string, options?: {
+            /** Expand ancestors to make the node visible (default: true) */
             expand?: boolean;
+            /** Also expand the target node itself to show its children (default: false for performance) */
+            expandTarget?: boolean;
             highlight?: boolean;
             scrollOptions?: ScrollIntoViewOptions;
             /** Scroll only within the nearest scrollable container (prevents page scroll) */
@@ -172,11 +190,22 @@ declare function $$render<T>(): {
             shouldDisplayContextMenuInDebugMode?: boolean;
             isLoading?: boolean;
             progressiveRender?: boolean;
-            renderBatchSize?: number;
+            initialBatchSize?: number;
+            maxBatchSize?: number;
             isRendering?: boolean;
             onRenderStart?: () => void;
             onRenderProgress?: (stats: RenderStats) => void;
             onRenderComplete?: (stats: RenderStats) => void;
+            /**
+             * Use flat/centralized rendering instead of recursive node rendering.
+             * This significantly improves performance for large trees by:
+             * - Removing the {#key changeTracker} block that destroys all nodes on any change
+             * - Using a single flat loop instead of recursive component instantiation
+             * - Allowing Svelte's keyed {#each} to efficiently diff only changed nodes
+             */
+            useFlatRendering?: boolean;
+            /** Indentation per level in flat rendering mode (CSS value, default: '1.5rem') */
+            flatIndentSize?: string;
             dragDropMode?: DragDropMode;
             dropZoneMode?: "floating" | "glow";
             dropZoneLayout?: "around" | "above" | "below" | "wave" | "wave2";
@@ -191,11 +220,15 @@ declare function $$render<T>(): {
              * Called before a drop is processed. Return false to cancel the drop.
              * Return { position, operation } to override the drop position or operation.
              * Return true or undefined to proceed normally.
+             * Can be async - return a Promise to show dialogs or perform async validation.
              */
             beforeDropCallback?: (dropNode: LTreeNode<T> | null, draggedNode: LTreeNode<T>, position: DropPosition, event: DragEvent | TouchEvent, operation: DropOperation) => boolean | {
                 position?: DropPosition;
                 operation?: DropOperation;
-            } | void;
+            } | void | Promise<boolean | {
+                position?: DropPosition;
+                operation?: DropOperation;
+            } | void>;
             onNodeDrop?: (dropNode: LTreeNode<T> | null, draggedNode: LTreeNode<T>, position: DropPosition, event: DragEvent | TouchEvent, operation: DropOperation) => void;
             contextMenuCallback?: (node: LTreeNode<T>, closeMenuCallback: () => void) => ContextMenuItem[];
             bodyClass?: string | null | undefined;
@@ -262,7 +295,10 @@ declare class __sveltets_Render<T> {
         getAllData: () => T[];
         closeContextMenu: () => void;
         scrollToPath: (path: string, options?: {
+            /** Expand ancestors to make the node visible (default: true) */
             expand?: boolean;
+            /** Also expand the target node itself to show its children (default: false for performance) */
+            expandTarget?: boolean;
             highlight?: boolean;
             scrollOptions?: ScrollIntoViewOptions;
             /** Scroll only within the nearest scrollable container (prevents page scroll) */
@@ -309,11 +345,22 @@ declare class __sveltets_Render<T> {
             shouldDisplayContextMenuInDebugMode?: boolean;
             isLoading?: boolean;
             progressiveRender?: boolean;
-            renderBatchSize?: number;
+            initialBatchSize?: number;
+            maxBatchSize?: number;
             isRendering?: boolean;
             onRenderStart?: (() => void) | undefined;
             onRenderProgress?: ((stats: RenderStats) => void) | undefined;
             onRenderComplete?: ((stats: RenderStats) => void) | undefined;
+            /**
+             * Use flat/centralized rendering instead of recursive node rendering.
+             * This significantly improves performance for large trees by:
+             * - Removing the {#key changeTracker} block that destroys all nodes on any change
+             * - Using a single flat loop instead of recursive component instantiation
+             * - Allowing Svelte's keyed {#each} to efficiently diff only changed nodes
+             */
+            useFlatRendering?: boolean;
+            /** Indentation per level in flat rendering mode (CSS value, default: '1.5rem') */
+            flatIndentSize?: string;
             dragDropMode?: DragDropMode;
             dropZoneMode?: "floating" | "glow";
             dropZoneLayout?: "around" | "above" | "below" | "wave" | "wave2";
@@ -328,11 +375,15 @@ declare class __sveltets_Render<T> {
              * Called before a drop is processed. Return false to cancel the drop.
              * Return { position, operation } to override the drop position or operation.
              * Return true or undefined to proceed normally.
+             * Can be async - return a Promise to show dialogs or perform async validation.
              */
             beforeDropCallback?: ((dropNode: LTreeNode<T> | null, draggedNode: LTreeNode<T>, position: DropPosition, event: DragEvent | TouchEvent, operation: DropOperation) => boolean | void | {
                 position?: DropPosition;
                 operation?: DropOperation;
-            }) | undefined;
+            } | Promise<boolean | void | {
+                position?: DropPosition;
+                operation?: DropOperation;
+            }>) | undefined;
             onNodeDrop?: ((dropNode: LTreeNode<T> | null, draggedNode: LTreeNode<T>, position: DropPosition, event: DragEvent | TouchEvent, operation: DropOperation) => void) | undefined;
             contextMenuCallback?: ((node: LTreeNode<T>, closeMenuCallback: () => void) => ContextMenuItem[]) | undefined;
             bodyClass?: string | null | undefined;
@@ -345,7 +396,7 @@ declare class __sveltets_Render<T> {
             scrollHighlightClass?: string | null | undefined;
             contextMenuXOffset?: number | null | undefined;
             contextMenuYOffset?: number | null | undefined;
-        }, "treeId" | "data" | "onNodeClicked" | "onNodeDragStart" | "onNodeDragOver" | "onNodeDrop" | "shouldToggleOnNodeClick" | "expandIconClass" | "collapseIconClass" | "leafIconClass" | "selectedNodeClass" | "dragOverNodeClass" | "dropZoneMode" | "treePathSeparator" | "idMember" | "pathMember" | "parentPathMember" | "levelMember" | "hasChildrenMember" | "isExpandedMember" | "displayValueMember" | "getDisplayValueCallback" | "searchValueMember" | "getSearchValueCallback" | "orderMember" | "isSorted" | "sortCallback" | "isDraggableMember" | "isDropAllowedMember" | "shouldDisplayDebugInformation" | "isSelectedMember" | "selectedNode" | "expandLevel" | "shouldUseInternalSearchIndex" | "initializeIndexCallback" | "searchText" | "indexerBatchSize" | "indexerTimeout" | "shouldDisplayContextMenuInDebugMode" | "dragDropMode" | "beforeDropCallback" | "contextMenuCallback" | "bodyClass" | "scrollHighlightTimeout" | "scrollHighlightClass" | "contextMenuXOffset" | "contextMenuYOffset">>) => void;
+        }, "treeId" | "data" | "shouldToggleOnNodeClick" | "expandIconClass" | "collapseIconClass" | "leafIconClass" | "selectedNodeClass" | "dragOverNodeClass" | "dropZoneMode" | "treePathSeparator" | "idMember" | "pathMember" | "parentPathMember" | "levelMember" | "hasChildrenMember" | "isExpandedMember" | "displayValueMember" | "getDisplayValueCallback" | "searchValueMember" | "getSearchValueCallback" | "orderMember" | "isSorted" | "sortCallback" | "isDraggableMember" | "isDropAllowedMember" | "shouldDisplayDebugInformation" | "isSelectedMember" | "selectedNode" | "expandLevel" | "shouldUseInternalSearchIndex" | "initializeIndexCallback" | "searchText" | "indexerBatchSize" | "indexerTimeout" | "shouldDisplayContextMenuInDebugMode" | "dragDropMode" | "onNodeClicked" | "onNodeDragStart" | "onNodeDragOver" | "beforeDropCallback" | "onNodeDrop" | "contextMenuCallback" | "bodyClass" | "scrollHighlightTimeout" | "scrollHighlightClass" | "contextMenuXOffset" | "contextMenuYOffset">>) => void;
     };
 }
 interface $$IsomorphicComponent {

package/dist/constants.generated.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "4.5.0";
+export declare const VERSION = "4.6.0";
 export declare const PACKAGE_NAME = "@keenmate/svelte-treeview";
 export declare const AUTHOR = "KeenMate";
 export declare const LICENSE = "MIT";

package/dist/constants.generated.js

@@ -1,6 +1,6 @@
 // Auto-generated file - do not edit manually
 // Generated by scripts/generate-constants.js
-export const VERSION = "4.5.0";
+export const VERSION = "4.6.0";
 export const PACKAGE_NAME = "@keenmate/svelte-treeview";
 export const AUTHOR = "KeenMate";
 export const LICENSE = "MIT";

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { default as Tree } from "./components/Tree.svelte";
 export type { LTreeNode, NodeId, VisualState } from "./ltree/ltree-node.svelte";
 export type { Ltree, DropPosition, DragDropMode, DropOperation, ContextMenuItem, InsertArrayResult, TreeChange, ApplyChangesResult } from "./ltree/types";
 export type { RenderStats } from "./components/RenderCoordinator.svelte";
+export type { NodeCallbacks, NodeConfig } from "./components/Tree.svelte";
 export { enableLogging, disableLogging, setLogLevel, setCategoryLevel, LOGGING_CATEGORIES } from "./logger";
 export { enablePerfLogging, disablePerfLogging, setPerfThreshold, isPerfLoggingEnabled, perfStart, perfEnd, perfMeasure, perfSummary } from "./perf-logger";
 export type { GlobalTreeviewAPI } from "./global-api";

package/dist/ltree/ltree.svelte.js

@@ -31,6 +31,9 @@ export function createLTree(_idMember, _pathMember, _parentPathMember, _levelMem
     let flatTreeNodes = [];
     let filteredTree = null;
     let isFiltered = false;
+    // Cache for visibleFlatNodes - only recompute when tree changes
+    let cachedVisibleFlatNodes = [];
+    let cachedVisibleFlatNodesTracker = null;
     // Async search indexing infrastructure
     let indexer = null;
     // Initialize indexer when search index is available
@@ -74,6 +77,54 @@ export function createLTree(_idMember, _pathMember, _parentPathMember, _levelMem
             }
             return Object.values(root.children);
         },
+        /**
+         * Returns a flat array of all visible nodes in render order (depth-first).
+         * A node is visible if all its ancestors are expanded.
+         * This is optimized for flat/centralized rendering without recursion.
+         *
+         * Note: This getter depends on changeTracker to ensure reactivity when
+         * nodes are expanded/collapsed or the tree structure changes.
+         * Results are cached to avoid recomputation on repeated access.
+         */
+        get visibleFlatNodes() {
+            // Explicitly read changeTracker to create reactive dependency
+            const _tracker = changeTracker;
+            // Return cached result if changeTracker hasn't changed
+            if (_tracker === cachedVisibleFlatNodesTracker && cachedVisibleFlatNodes.length > 0) {
+                // console.log(`[visibleFlatNodes] Cache HIT - returning ${cachedVisibleFlatNodes.length} nodes`);
+                return cachedVisibleFlatNodes;
+            }
+            const computeStart = performance.now();
+            const startRoot = this.isFiltered ? filteredRoot : root;
+            if (!startRoot?.children || !_tracker) {
+                cachedVisibleFlatNodes = [];
+                cachedVisibleFlatNodesTracker = _tracker;
+                return cachedVisibleFlatNodes;
+            }
+            const result = [];
+            const self = this;
+            function traverse(node) {
+                // Get children and optionally sort them
+                let children = Object.values(node.children);
+                if (self.isSorted && children.length > 0) {
+                    children = self.sortCallback(children);
+                }
+                for (const child of children) {
+                    result.push(child);
+                    // Only traverse into children if this node is expanded
+                    if (child.isExpanded && child.hasChildren) {
+                        traverse(child);
+                    }
+                }
+            }
+            traverse(startRoot);
+            const computeTime = performance.now() - computeStart;
+            console.log(`[visibleFlatNodes] Computed ${result.length} nodes in ${computeTime.toFixed(2)}ms`);
+            // Cache the result
+            cachedVisibleFlatNodes = result;
+            cachedVisibleFlatNodesTracker = _tracker;
+            return result;
+        },
         get statistics() {
             const filteredNodeCount = isFiltered ? filteredTree?.length || 0 : 0;
             const indexerStatus = indexer?.getStatus() || { isProcessing: false, queueSize: 0 };
@@ -408,31 +459,46 @@ export function createLTree(_idMember, _pathMember, _parentPathMember, _levelMem
             }
         },
         expandNodes: function (path, noEmitChanges = false) {
+            perfStart(`[${_treeId}] expandNodes`);
             let node = this.isFiltered ? filteredRoot : root;
+            let hasChanges = false;
             const segments = path.split(this.treePathSeparator);
             for (let i = 0; i < segments.length; i++) {
                 const segment = segmentPrefix + segments[i];
                 if (node.children.hasOwnProperty(segment)) {
                     node = node.children[segment];
-                    node.isExpanded = true;
+                    // Only mark as changed if actually changing from collapsed to expanded
+                    if (!node.isExpanded) {
+                        node.isExpanded = true;
+                        hasChanges = true;
+                    }
                 }
             }
-            if (!noEmitChanges) {
+            // Only emit changes if something actually changed
+            if (!noEmitChanges && hasChanges) {
+                console.log(`[Tree ${_treeId}] expandNodes triggering re-render for path: ${path}`);
                 this._emitTreeChanged();
             }
+            perfEnd(`[${_treeId}] expandNodes`);
             return this; // Return the API object for chaining
         },
         collapseNodes: function (path, noEmitChanges = false) {
             let node = this.isFiltered ? filteredRoot : this.root;
+            let hasChanges = false;
             const segments = path.split(this.treePathSeparator);
             for (let i = 0; i < segments.length; i++) {
                 const segment = segmentPrefix + segments[i];
                 if (node.children.hasOwnProperty(segment)) {
                     node = node.children[segment];
-                    node.isExpanded = false;
+                    // Only mark as changed if actually changing from expanded to collapsed
+                    if (node.isExpanded) {
+                        node.isExpanded = false;
+                        hasChanges = true;
+                    }
                 }
             }
-            if (!noEmitChanges) {
+            // Only emit changes if something actually changed
+            if (!noEmitChanges && hasChanges) {
                 this._emitTreeChanged();
             }
             return this; // Return the API object for chaining
@@ -613,8 +679,8 @@ export function createLTree(_idMember, _pathMember, _parentPathMember, _levelMem
                 }
             }
             const newPath = newParentPath ? `${newParentPath}${this.treePathSeparator}${newSegment}` : newSegment;
-            // Update source node's path and parentPath
             const oldPath = sourceNode.path;
+            // Update source node's path and parentPath
             sourceNode.path = newPath;
             sourceNode.pathSegment = newSegment;
             sourceNode.parentPath = newParentPath || null;

package/dist/ltree/types.d.ts

@@ -71,6 +71,8 @@ export interface Ltree<T> {
     isDropAllowedMember: string | null | undefined;
     shouldDisplayDebugInformation: boolean | null | undefined;
     get tree(): LTreeNode<T>[];
+    /** Flat array of all visible nodes in render order (depth-first, respects isExpanded) */
+    get visibleFlatNodes(): LTreeNode<T>[];
     get statistics(): {
         nodeCount: number;
         maxLevel: number;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@keenmate/svelte-treeview",
-	"version": "4.5.0",
+	"version": "4.6.0",
 	"scripts": {
 		"dev": "vite dev --port 17777",
 		"build": "vite build && npm run prepack",