@syncfusion/ej2-navigations 34.1.31 → 34.2.2

package/dist/global/index.d.ts

@@ -1,6 +1,6 @@
 /*!
 *  filename: index.d.ts
-*  version : 34.1.31
+*  version : 34.2.2
 *  Copyright Syncfusion Inc. 2001 - 2025. All rights reserved.
 *  Use of this code is subject to the terms of our license.
 *  A copy of the current license can be obtained at any time by e-mailing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncfusion/ej2-navigations",
-  "version": "34.1.31",
+  "version": "34.2.2",
   "description": "A package of Essential JS 2 navigation components such as Tree-view, Tab, Toolbar, Context-menu, and Accordion which is used to navigate from one page to another",
   "author": "Syncfusion Inc.",
   "license": "SEE LICENSE IN license",
@@ -8,12 +8,13 @@
   "module": "./index.js",
   "es2015": "./dist/es6/ej2-navigations.es5.js",
   "dependencies": {
-    "@syncfusion/ej2-base": "~34.1.30",
-    "@syncfusion/ej2-buttons": "~34.1.30",
-    "@syncfusion/ej2-data": "~34.1.29",
-    "@syncfusion/ej2-inputs": "~34.1.30",
-    "@syncfusion/ej2-lists": "~34.1.30",
-    "@syncfusion/ej2-popups": "~34.1.29"
+    "@syncfusion/ej2-base": "~34.2.2",
+    "@syncfusion/ej2-buttons": "~34.2.2",
+    "@syncfusion/ej2-data": "~34.2.2",
+    "@syncfusion/ej2-inputs": "~34.2.2",
+    "@syncfusion/ej2-lists": "~34.2.2",
+    "@syncfusion/ej2-notifications": "~34.2.2",
+    "@syncfusion/ej2-popups": "~34.2.2"
   },
   "devDependencies": {},
   "keywords": [

package/src/treeview/treeview-model.d.ts

@@ -1,4 +1,4 @@
-import { Component, EmitType, isUndefined, Browser, compile, isNullOrUndefined, SanitizeHtmlHelper, animationMode } from '@syncfusion/ej2-base';import { Property, INotifyPropertyChanged, NotifyPropertyChanges, ChildProperty, Complex } from '@syncfusion/ej2-base';import { Event, EventHandler, KeyboardEvents, KeyboardEventArgs } from '@syncfusion/ej2-base';import { rippleEffect, Effect, Animation, AnimationOptions, RippleOptions, remove } from '@syncfusion/ej2-base';import { Draggable, DragEventArgs, Droppable, DropEventArgs } from '@syncfusion/ej2-base';import { getElement } from '@syncfusion/ej2-base';import { addClass, removeClass, closest, matches, detach, select, selectAll, isVisible, append } from '@syncfusion/ej2-base';import { DataManager, Query } from '@syncfusion/ej2-data';import { isNullOrUndefined as isNOU, Touch, TapEventArgs, getValue, setValue, extend, merge, attributes } from '@syncfusion/ej2-base';import { ListBase, ListBaseOptions, AriaAttributesMapping, FieldsMapping } from '@syncfusion/ej2-lists';import { createCheckBox, rippleMouseHandler } from '@syncfusion/ej2-buttons';import { Input, InputObject } from '@syncfusion/ej2-inputs';import { createSpinner, showSpinner, hideSpinner } from '@syncfusion/ej2-popups';
+import { Component, EmitType, isUndefined, Browser, compile, isNullOrUndefined, SanitizeHtmlHelper, animationMode } from '@syncfusion/ej2-base';import { Property, INotifyPropertyChanged, NotifyPropertyChanges, ChildProperty, Complex } from '@syncfusion/ej2-base';import { Event, EventHandler, KeyboardEvents, KeyboardEventArgs } from '@syncfusion/ej2-base';import { rippleEffect, Effect, Animation, AnimationOptions, RippleOptions, remove } from '@syncfusion/ej2-base';import { Draggable, DragEventArgs, Droppable, DropEventArgs } from '@syncfusion/ej2-base';import { getElement } from '@syncfusion/ej2-base';import { addClass, removeClass, closest, matches, detach, select, selectAll, isVisible, append } from '@syncfusion/ej2-base';import { DataManager, Query } from '@syncfusion/ej2-data';import { isNullOrUndefined as isNOU, Touch, TapEventArgs, getValue, setValue, extend, merge, attributes } from '@syncfusion/ej2-base';import { ListBase, ListBaseOptions, AriaAttributesMapping, FieldsMapping } from '@syncfusion/ej2-lists';import { createCheckBox, rippleMouseHandler } from '@syncfusion/ej2-buttons';import { Input, InputObject } from '@syncfusion/ej2-inputs';import { createSpinner, showSpinner, hideSpinner } from '@syncfusion/ej2-popups';import { Skeleton } from '@syncfusion/ej2-notifications';
 import {ExpandOnSettings,SortOrder,FailureEventArgs,DataBoundEventArgs,DataSourceChangedEventArgs,DrawNodeEventArgs,NodeKeyPressEventArgs,NodeCheckEventArgs,NodeClickEventArgs,NodeExpandEventArgs,DragAndDropEventArgs,NodeEditEventArgs,NodeSelectEventArgs} from "./treeview";
 import {ComponentModel} from '@syncfusion/ej2-base';
 
@@ -200,6 +200,31 @@ export interface TreeViewModel extends ComponentModel{
      */
     allowTextWrap?: boolean;
 
+    /**
+     * Enables virtual rendering mode for the TreeView, where only the nodes visible in the viewport are rendered in the DOM.
+     * This significantly improves rendering performance when working with large datasets (thousands of nodes).
+     *
+     * When set to `true`, you must also set the `height` property to a fixed pixel value so the component can calculate
+     * the visible window and the total scrollable height.
+     *
+     * @default false
+     * @remarks
+     * - Requires `height` to be set to a positive pixel value (e.g. `'400px'` or `400`).
+     * - Animations on expand/collapse are suppressed in virtual mode to avoid layout artifacts.
+     * - Drag-and-drop and editing work normally; the DOM is refreshed after each interaction.
+     * - `ensureVisible()` is augmented to first scroll the virtualized container before attempting DOM access.
+     */
+    enableVirtualization?: boolean;
+
+    /**
+     * Specifies the fixed height of the TreeView container when `enableVirtualization` is `true`.
+     * Accepts a pixel string (e.g. `'400px'`) or a numeric pixel value (e.g. `400`).
+     * This value is used to calculate the virtual viewport and the total scrollable height.
+     *
+     * @default undefined
+     */
+    height?: string | number;
+
     /**
      * Specifies the type of animation applied on expanding and collapsing the nodes along with duration.
      *

package/src/treeview/treeview.d.ts

@@ -553,6 +553,54 @@ export declare class TreeView extends Component<HTMLElement> implements INotifyP
     private OldCheckedData;
     private isHiddenItem;
     private nodeIndex;
+    /** Flat ordered list of all currently-visible (non-collapsed) tree nodes. */
+    private virtualFlatNodes;
+    /** Maps node id → index in virtualFlatNodes for O(1) lookups. */
+    private virtualNodeMap;
+    /** Set of expanded node IDs for O(1) lookup performance during flattening (avoids array indexOf). */
+    private virtualExpandedNodesSet;
+    /** Set of checked node IDs for O(1) lookup performance during flattening. */
+    private virtualCheckedNodesSet;
+    /** Set of indeterminate node IDs — persists across flattenVisibleNodes() rebuilds. */
+    private virtualIndeterminateNodesSet;
+    /** Set of selected node IDs for O(1) lookup performance during flattening. */
+    private virtualSelectedNodesSet;
+    /** Row height in pixels, measured from the first rendered item or set to 40 as a default. */
+    private virtualItemHeight;
+    /** Height of the scrollable container in pixels. */
+    private virtualViewportHeight;
+    /** scrollTop captured during the previous scroll handler invocation. */
+    private virtualPrevScrollTop;
+    /** Index of the first rendered row in the current window. */
+    private virtualStartIndex;
+    /** Index one past the last rendered row in the current window. */
+    private virtualEndIndex;
+    /** Extra rows rendered above and below the visible window to smooth scrolling. */
+    private virtualOverscanCount;
+    /** RequestAnimationFrame handle used for throttling scroll events. */
+    private virtualScrollRAF;
+    /** The `.e-mask-parent` overlay element shown during fast scroll. */
+    private virtualMaskElement;
+    /** Bound scroll handler stored for later removeEventListener. */
+    private virtualScrollBound;
+    /** Skeleton component instances inside the mask overlay. */
+    private skeletonInstances;
+    /** Set to true whenever the flat node list must be rebuilt on next render. */
+    private virtualTreeDirty;
+    /** The data-uid of the currently keyboard-focused node in virtual mode (persists across re-renders). */
+    private virtualFocusedId;
+    /**
+     * Set to true by the document-level `keydown` handler when the user presses
+     * the Tab key.  The browser will auto-scroll the focused element into view
+     * immediately after focus, which fires a `scroll` event on the TreeView
+     * container.  We want to skip the re-render that the virtual scroll handler
+     * would otherwise trigger, because the element being focused is already
+     * rendered (it is the single `<li tabindex="0">` of the current window) and
+     * re-rendering would tear down the DOM element that is currently holding
+     * focus.  The flag is consumed (reset to `false`) inside `onVirtualScroll`
+     * after the auto-scroll has been handled.
+     */
+    private virtualSkipNextScrollRender;
     /**
      * Indicates whether the TreeView allows drag and drop of nodes. To drag and drop a node in
      * desktop, hold the mouse on the node, drag it to the target node and drop the node by releasing
@@ -593,6 +641,29 @@ export declare class TreeView extends Component<HTMLElement> implements INotifyP
      * @default false
      */
     allowTextWrap: boolean;
+    /**
+     * Enables virtual rendering mode for the TreeView, where only the nodes visible in the viewport are rendered in the DOM.
+     * This significantly improves rendering performance when working with large datasets (thousands of nodes).
+     *
+     * When set to `true`, you must also set the `height` property to a fixed pixel value so the component can calculate
+     * the visible window and the total scrollable height.
+     *
+     * @default false
+     * @remarks
+     * - Requires `height` to be set to a positive pixel value (e.g. `'400px'` or `400`).
+     * - Animations on expand/collapse are suppressed in virtual mode to avoid layout artifacts.
+     * - Drag-and-drop and editing work normally; the DOM is refreshed after each interaction.
+     * - `ensureVisible()` is augmented to first scroll the virtualized container before attempting DOM access.
+     */
+    enableVirtualization: boolean;
+    /**
+     * Specifies the fixed height of the TreeView container when `enableVirtualization` is `true`.
+     * Accepts a pixel string (e.g. `'400px'`) or a numeric pixel value (e.g. `400`).
+     * This value is used to calculate the virtual viewport and the total scrollable height.
+     *
+     * @default undefined
+     */
+    height: string | number;
     /**
      * Specifies the type of animation applied on expanding and collapsing the nodes along with duration.
      *
@@ -1127,6 +1198,18 @@ export declare class TreeView extends Component<HTMLElement> implements INotifyP
     private nodeCheckAction;
     private addCheck;
     private removeCheck;
+    /**
+     * Recursively sets the `isChecked` state of all descendants of the node with
+     * `parentId` in `virtualFlatNodes`, keeping `checkedNodes` and
+     * `virtualCheckedNodesSet` in sync.  Used in virtual mode to honor the
+     * `autoCheck` cascade when a parent checkbox is toggled.
+     *
+     * @param {string} parentId - The `data-uid` of the parent whose descendants should be updated.
+     * @param {boolean} isChecked - The new state to apply to every descendant.
+     * @returns {void}
+     * @private
+     */
+    private setVirtualChildCheckState;
     private getCheckEvent;
     private finalize;
     private setTextWrap;
@@ -1353,6 +1436,212 @@ export declare class TreeView extends Component<HTMLElement> implements INotifyP
     private dmFailure;
     private updatePreviousText;
     private getHierarchicalParentId;
+    /**
+     * Parses the `height` property (string like '400px' or number) to a pixel value.
+     * Returns 0 if the value cannot be determined.
+     *
+     * @returns {number} Pixel height.
+     * @private
+     */
+    private parseHeightToPixels;
+    /**
+     * Measures the height of the first rendered list item so subsequent calculations
+     * use real layout values.  Falls back to the stored `virtualItemHeight` default (40).
+     *
+     * @returns {number} Row height in pixels.
+     * @private
+     */
+    private measureVirtualItemHeight;
+    /**
+     * Rebuilds the cached Sets for checked/selected nodes to enable O(1) lookup
+     * during the flatten operation instead of O(n) array indexOf calls.
+     *
+     * @returns {void}
+     * @private
+     */
+    private rebuildVirtualCheckCache;
+    /**
+     * Recursively walks the treeData (or groupedData for flat lists) and builds
+     * `virtualFlatNodes` — an ordered list of every node that is currently visible
+     * (i.e. its ancestors are all expanded). Uses cached Sets for O(1) state lookups.
+     *
+     * @returns {VirtualNodeData[]} Ordered flat list of visible nodes.
+     * @private
+     */
+    private flattenVisibleNodes;
+    /**
+     * Recursive helper for `flattenVisibleNodes`.
+     *
+     * @param {Object[]} nodes - Array of raw data objects at this level.
+     * @param {number} level - 1-based depth level.
+     * @param {string | null} parentId - The parent node id, or null for root.
+     * @param {VirtualNodeData[]} result - Accumulator array.
+     * @returns {void}
+     * @private
+     */
+    private flattenNodeRecursive;
+    /**
+     * Checks whether a raw datasource node has child records.
+     *
+     * @param {Object} raw - Raw datasource object.
+     * @returns {boolean} True if children exist.
+     * @private
+     */
+    private hasChildRecords;
+    /**
+     * Rebuilds `virtualNodeMap` (id → index) from the current `virtualFlatNodes`.
+     *
+     * @returns {void}
+     * @private
+     */
+    private rebuildVirtualNodeMap;
+    private getVirtualWindow;
+    private getVirtualWindowAt;
+    private getVirtualPadding;
+    /**
+     * Renders the virtual window into a **nested** `<ul>/<li>` hierarchy identical to
+     * the non-virtualized DOM structure.
+     *
+     * ## Scroll math
+     * The flat-index ↔ pixel mapping stays unchanged: every entry in
+     * `virtualFlatNodes` represents exactly one `itemHeight` row.
+     * `paddingTop = startIndex * itemHeight` and
+     * `paddingBottom = (total - endIndex) * itemHeight` keep the scrollbar
+     * thumb in the correct position.
+     *
+     * ## Ancestor injection
+     * When `startIndex` points at a child node whose ancestor(s) have already
+     * scrolled above the viewport (their flat indices are < startIndex), the
+     * ancestors would normally be missing from the DOM, forcing the children to
+     * fall back to the root `<ul>` as flat siblings — producing wrong HTML.
+     *
+     * To fix this, before rendering the window we walk the ancestor chain of the
+     * first visible node and collect every ancestor that lies **outside** the
+     * window.  Those ancestors are injected as real `<li>` containers at the
+     * very top of the root `<ul>`.  To compensate for their presence, `paddingTop`
+     * is reduced by `injectedCount * itemHeight` so the total scroll height
+     * remains the same.
+     *
+     * Once the ancestors are in the DOM they are registered in `renderedParentMap`
+     * so the normal window-rendering loop can nest children inside them exactly
+     * as it does when both parent and child are in the same window.
+     *
+     * @returns {void}
+     * @private
+     */
+    private renderVirtualItems;
+    /**
+     * Creates a single `<li>` element for the virtual window representing `node`.
+     *
+     * @param {VirtualNodeData} node - The node data.
+     * @param {boolean} _isFirst - True if this is the first rendered item (unused here but kept for potential override).
+     * @returns {HTMLElement} The constructed `<li>` element.
+     * @private
+     */
+    private createVirtualListItem;
+    /**
+     * Initialises the virtual-scrolling layout:
+     * 1. Adds the `e-virtualization` CSS class and applies a fixed `height` + `overflow-y`.
+     * 2. Flattens all visible nodes into `virtualFlatNodes`.
+     * 3. Measures item height and viewport height.
+     * 4. Computes the initial window and renders it.
+     * 5. Wires the scroll event handler.
+     *
+     * @returns {void}
+     * @private
+     */
+    private initVirtualization;
+    /**
+     * Wires the scroll event listener on the TreeView element.
+     *
+     * @returns {void}
+     * @private
+     */
+    private wireVirtualScrollEvents;
+    /**
+     * Removes the scroll event listener previously wired by `wireVirtualScrollEvents`.
+     *
+     * @returns {void}
+     * @private
+     */
+    private unwireVirtualScrollEvents;
+    /**
+     * Scroll handler for the virtual TreeView.  Throttled via `requestAnimationFrame`.
+     * Shows the loading mask during fast scrolls, re-renders the window, then hides the mask.
+     *
+     * @returns {void}
+     * @private
+     */
+    private onVirtualScroll;
+    /**
+     * Creates the skeleton mask overlay used to indicate loading during fast scrolls.
+     * Skeleton instances are stored in `skeletonInstances` for later disposal.
+     *
+     * @returns {void}
+     * @private
+     */
+    private createVirtualMask;
+    /**
+     * Refreshes the mask position so it always overlays the TreeView's viewport.
+     * Called on every show / scroll, since `position:fixed` is relative to the
+     * page viewport, not to the TreeView scroll container.
+     *
+     * @returns {void}
+     * @private
+     */
+    private updateMaskPosition;
+    /**
+     * Destroys all skeleton instances and removes the mask overlay from the DOM.
+     *
+     * @returns {void}
+     * @private
+     */
+    private destroyVirtualMask;
+    /**
+     * Positions and shows the skeleton mask at the current `scrollTop` position.
+     *
+     * @param {number} _scrollTop - Current scrollTop of the container.
+     * @returns {void}
+     * @private
+     */
+    private showVirtualMask;
+    /**
+     * Hides the skeleton mask overlay after the virtual window has been rendered.
+     *
+     * @returns {void}
+     * @private
+     */
+    private hideVirtualMask;
+    /**
+     * Ensures the node identified by `id` is scrolled into view inside the virtual container.
+     * If the node falls outside the rendered window, the container's `scrollTop` is adjusted so
+     * that the node becomes visible, the window is re-computed and `renderVirtualItems` is called.
+     *
+     * @param {string} id - The `data-uid` of the target node.
+     * @returns {void}
+     * @private
+     */
+    private ensureVirtualNodeVisible;
+    private handleVirtualExpand;
+    private handleVirtualCollapse;
+    /**
+     * Updates the selected state of a node in `virtualFlatNodes` and re-renders the window.
+     *
+     * @param {string} id - The `data-uid` of the target node.
+     * @param {boolean} isSelected - Whether the node is now selected.
+     * @returns {void}
+     * @private
+     */
+    private updateVirtualNodeSelection;
+    /**
+     * Updates the checkbox state of a node in `virtualFlatNodes` and re-renders the window.
+     *
+     * @param {string} id - The `data-uid` of the target node.
+     * @param {'check' | 'uncheck' | 'indeterminate'} state - The new check state.
+     * @returns {void}
+     * @private
+     */
+    private updateVirtualNodeCheckState;
     /**
      * Called internally if any of the property value changed.
      *