@keenmate/svelte-treeview 5.0.0-rc01 → 5.0.0-rc03

package/README.md

@@ -6,74 +6,52 @@ A high-performance, feature-rich hierarchical tree view component for Svelte 5 w
 
 Browse interactive code examples and the full API reference at **[svelte-treeview.keenmate.dev](https://svelte-treeview.keenmate.dev)**
 
-## v5.0: Core/Renderer Split
+## What's New in v5.0.0-rc03
 
-> [!IMPORTANT]
-> **In version 5, the tree core (data structure, expand/collapse, search, drag & drop logic) has been completely separated from the renderer.** The library now ships with multiple built-in renderers — the classic HTML `Tree`, a high-performance `CanvasTree` (with tree, balanced, fishbone, radial, box, and sunburst layouts) — and the architecture is open for you to build your own custom renderers on top of the same core.
-
-This means you can:
-- Use the built-in renderers as-is for common use cases
-- Create entirely custom visualizations (WebGL, SVG, etc.) powered by the same tree core
-- Mix and match — use the HTML tree for editing and a canvas renderer for overview
-
-## New in v4.7: Per-Node Drop Position Restrictions
+- **Unified Context Menu API**: New shared type system (`ContextMenuItem`, `ContextMenuDivider`, `ContextMenuEntry`) used by both svelte-treeview and canvas-tree. Breaking: `title` → `label`, `callback` → `onclick`, `isDivider` → separate `ContextMenuDivider` type.
+- **Context menu features**: Keyboard shortcuts, nested submenus, named dividers (`──── Section ────`), `isVisible`/`isDisabled` per item, `className="danger"`, async `onclick`.
+- **Svelte context menu components**: `ContextMenuItemC` and `ContextMenuDividerC` for declarative snippet-based menus alongside the callback approach.
+- **Accordion expand**: `accordionExpand={true}` — expanding a node auto-collapses its siblings.
+- **Toggle icon mode**: `toggleIconMode="rotate"` (default) smoothly rotates the expand icon vs `"swap"` which switches between two icons.
+- **Fix**: Expand/collapse icon not updating in flat rendering mode.
+- **Fix**: `vite.config.ts` no longer requires `@types/node`.
 
-> [!NOTE]
-> **You can now restrict which drop positions (above/below/child) are allowed per node.**
+## v5.0: Core/Renderer Split + Virtual Scroll
 
-Use `getAllowedDropPositionsCallback` for dynamic logic or `allowedDropPositionsMember` for server data:
-```typescript
-// Files can only have siblings, trash only accepts children
-function getAllowedDropPositions(node) {
-  if (node.data?.type === 'file') return ['above', 'below'];
-  if (node.data?.type === 'trash') return ['child'];
-  return undefined; // all positions allowed (default)
-}
-```
+> [!IMPORTANT]
+> **In version 5, the tree core (data structure, expand/collapse, search, drag & drop logic) has been completely separated from the renderer.** The architecture is open for you to build your own custom renderers on top of the same core via `TreeProvider` and `TreeController`.
 
-## v4.6: Progressive Flat Rendering
+**Key changes in v5:**
+- **Core/Renderer split**: Use the built-in HTML `Tree` renderer, or create custom visualizations (Canvas, WebGL, SVG) via `TreeProvider` + `TreeController`
+- **Virtual scroll**: Render 50,000+ node trees smoothly with `virtualScroll={true}` — only ~50 DOM nodes at any time
+- **Canvas companion**: For canvas rendering, install [`@keenmate/svelte-treeview-canvas`](https://github.com/keenmate/svelte-treeview-canvas)
+- **Drop position naming**: `'above'`/`'below'` renamed to `'before'`/`'after'` (CSS classes and events updated accordingly)
 
-> [!NOTE]
-> **The tree now uses progressive flat rendering by default for significantly improved performance.**
+### Rendering Modes
 
-**What this means:**
-- The tree renders immediately with the first batch of nodes (~20 by default)
-- Remaining nodes are rendered progressively in subsequent frames
-- For large trees (5000+ nodes), you'll see nodes appear over ~100-500ms instead of a single long freeze
-- The UI remains responsive during rendering
+| Mode | Props | DOM Nodes | Best For |
+|------|-------|-----------|----------|
+| Recursive | `useFlatRendering={false}` | All | Small trees (<100 nodes) |
+| Flat (default) | `useFlatRendering={true}` | All | Medium trees (100–10K) |
+| Virtual | `virtualScroll={true}` | ~50 | Large trees (10K+) |
 
-**Configuration options:**
 ```svelte
-<Tree
-  {data}
-  useFlatRendering={true}   <!-- Default: true (flat mode) -->
-  progressiveRender={true}  <!-- Default: true (batched rendering) -->
-  initialBatchSize={20}     <!-- First batch size (default: 20) -->
-  maxBatchSize={500}        <!-- Maximum batch size cap (default: 500) -->
-/>
-```
-
-**Exponential batching:** The first batch renders 20 nodes instantly, then doubles each frame (20 → 40 → 80 → 160 → 320 → 500...) for optimal perceived performance.
+<!-- Virtual scroll for large trees -->
+<Tree {data} virtualScroll={true} virtualContainerHeight="500px" />
 
-**To use the legacy recursive rendering:**
-```svelte
-<Tree
-  {data}
-  useFlatRendering={false}  <!-- Uses recursive Node components -->
-/>
+<!-- Flat mode (default) with progressive batching -->
+<Tree {data} progressiveRender={true} initialBatchSize={20} maxBatchSize={500} />
 ```
 
-Recursive mode may be preferred for very small trees or when you need the `{#key changeTracker}` behavior that recreates all nodes on any change.
-
 ## Features
 
 - **Svelte 5 Native**: Built specifically for Svelte 5 with full support for runes and modern Svelte patterns
-- **High Performance**: Flat rendering mode with progressive loading for 5000+ nodes
-- **Drag & Drop**: Built-in drag and drop with position control (above/below/child), touch support, and async validation
+- **High Performance**: Flat rendering with progressive loading, virtual scroll for 50,000+ nodes
+- **Drag & Drop**: Built-in drag and drop with position control (before/after/child), touch support, and async validation
 - **Tree Editing**: Built-in methods for add, move, remove operations with automatic path management
 - **Search & Filter**: Integrated FlexSearch for fast, full-text search capabilities
 - **Flexible Data Sources**: Works with any hierarchical data structure
-- **Context Menus**: Dynamic right-click menus with callback-based generation, icons, disabled states
+- **Context Menus**: Dynamic right-click menus with shortcuts, submenus, named dividers, and two API approaches (callback or Svelte components)
 - **Visual Customization**: Extensive styling options and icon customization
 - **TypeScript Support**: Full TypeScript support with comprehensive type definitions
 - **Accessibility**: Built with accessibility in mind
@@ -155,14 +133,14 @@ import '@keenmate/svelte-treeview/styles.scss';
   idMember="path"
   pathMember="path"
   selectedNodeClass="ltree-selected-bold"
-  onNodeClicked={(node) => console.log('Clicked:', node.data.name)}
+  onNodeClicked={(node) => console.log('Clicked:', node.data?.name)}
 >
   {#snippet nodeTemplate(node)}
     <div class="d-flex align-items-center">
-      <span class="me-2">{node.data.icon}</span>
-      <strong>{node.data.name}</strong>
-      {#if node.data.size}
-        <small class="text-muted ms-2">({node.data.size})</small>
+      <span class="me-2">{node.data?.icon}</span>
+      <strong>{node.data?.name}</strong>
+      {#if node.data?.size}
+        <small class="text-muted ms-2">({node.data?.size})</small>
       {/if}
     </div>
   {/snippet}
@@ -277,13 +255,13 @@ For complete FlexSearch documentation, visit: [FlexSearch Options](https://githu
   ];
 
   function onDragStart(node, event) {
-    console.log('Dragging:', node.data.name);
+    console.log('Dragging:', node.data?.name);
   }
 
   // Same-tree moves are auto-handled - this callback is for notification/custom logic
   function onDrop(dropNode, draggedNode, position, event, operation) {
-    console.log(`Dropped ${draggedNode.data.name} ${position} ${dropNode?.data.name}`);
-    // position is 'above', 'below', or 'child'
+    console.log(`Dropped ${draggedNode.data?.name} ${position} ${dropNode?.data?.name}`);
+    // position is 'before', 'after', or 'child'
     // operation is 'move' or 'copy' (Ctrl+drag)
   }
 </script>
@@ -303,16 +281,16 @@ For complete FlexSearch documentation, visit: [FlexSearch Options](https://githu
 
 #### Drop Position Control
 
-When using `dropZoneMode="floating"` (default), users can choose where to drop:
-- **Above**: Insert as sibling before the target node
-- **Below**: Insert as sibling after the target node
+When using `dropZoneMode="floating"`, users can choose where to drop:
+- **Before**: Insert as sibling before the target node
+- **After**: Insert as sibling after the target node
 - **Child**: Insert as child of the target node
 
 #### Per-Node Drop Position Restrictions
 
 You can restrict which drop positions are allowed per node. This is useful for:
-- **Trash/Recycle Bin**: Only allow dropping INTO (child), not above/below
-- **Files**: Only allow above/below (can't drop INTO a file)
+- **Trash/Recycle Bin**: Only allow dropping INTO (child), not before/after
+- **Files**: Only allow before/after (can't drop INTO a file)
 - **Folders**: Allow all positions (default)
 
 ```svelte
@@ -321,7 +299,7 @@ You can restrict which drop positions are allowed per node. This is useful for:
 
   // Dynamic callback approach
   function getAllowedDropPositions(node: LTreeNode<MyItem>): DropPosition[] | null {
-    if (node.data?.type === 'file') return ['above', 'below'];
+    if (node.data?.type === 'file') return ['before', 'after'];
     if (node.data?.type === 'trash') return ['child'];
     return undefined; // all positions allowed
   }
@@ -363,7 +341,7 @@ Use `beforeDropCallback` to validate or modify drops, including async operations
     if (position === 'child' && !dropNode.data.isFolder) {
       const confirmed = await showConfirmDialog('Drop as sibling instead?');
       if (!confirmed) return false;
-      return { position: 'below' }; // Override position
+      return { position: 'after' }; // Override position
     }
 
     // Proceed normally
@@ -404,7 +382,7 @@ The tree provides built-in methods for programmatic editing:
     const siblings = treeRef.getSiblings(selectedNode.path);
     const index = siblings.findIndex(s => s.path === selectedNode.path);
     if (index > 0) {
-      treeRef.moveNode(selectedNode.path, siblings[index - 1].path, 'above');
+      treeRef.moveNode(selectedNode.path, siblings[index - 1].path, 'before');
     }
   }
 
@@ -423,18 +401,18 @@ The tree provides built-in methods for programmatic editing:
 />
 ```
 
-**Note**: When using `orderMember`, the tree automatically calculates sort order values when moving nodes with 'above' or 'below' positions.
+**Note**: When using `orderMember`, the tree automatically calculates sort order values when moving nodes with 'before' or 'after' positions.
 
 ### With Context Menus
 
-The tree supports context menus with two approaches: callback-based (recommended) and snippet-based.
+The tree supports context menus with two approaches: **callback-based** (imperative, shared with web components) and **snippet + component** (declarative, Svelte-only).
 
 #### Callback-Based Context Menus
 
 ```svelte
 <script lang="ts">
   import { Tree } from '@keenmate/svelte-treeview';
-  import type { ContextMenuItem } from '@keenmate/svelte-treeview';
+  import type { ContextMenuEntry } from '@keenmate/svelte-treeview';
 
   const data = [
     { path: '1', name: 'Documents', type: 'folder', canEdit: true, canDelete: true },
@@ -442,45 +420,21 @@ The tree supports context menus with two approaches: callback-based (recommended
     { path: '2', name: 'Images', type: 'folder', canEdit: false, canDelete: true }
   ];
 
-  function createContextMenu(node): ContextMenuItem[] {
-    const items: ContextMenuItem[] = [];
-
-    // Always available
-    items.push({
-      icon: '📂',
-      title: 'Open',
-      callback: () => alert(`Opening ${node.data.name}`)
-    });
-
-    // Conditional actions based on node data
-    if (node.data.canEdit) {
-      items.push({
-        icon: '✏️',
-        title: 'Edit',
-        callback: () => alert(`Editing ${node.data.name}`)
-      });
-    }
-
-    if (node.data.canDelete) {
-      items.push({
-        icon: '🗑️',
-        title: 'Delete',
-        callback: () => confirm(`Delete ${node.data.name}?`) && alert('Deleted!')
-      });
-    }
-
-    // Divider
-    items.push({ isDivider: true });
-
-    // Disabled item example
-    items.push({
-      icon: '🔒',
-      title: 'Restricted Action',
-      isDisabled: true,
-      callback: () => {}
-    });
-
-    return items;
+  function createContextMenu(node, close: () => void): ContextMenuEntry[] {
+    return [
+      { label: 'Open', icon: '📂', shortcut: 'O',
+        onclick: () => { alert(`Opening ${node.data?.name}`); close(); } },
+      { label: 'Edit', icon: '✏️', shortcut: 'E', isVisible: node.data?.canEdit,
+        onclick: () => { alert(`Editing ${node.data?.name}`); close(); } },
+      { label: 'Export As...', icon: '📤', children: [
+          { label: 'JSON', shortcut: 'J', onclick: () => { exportAs(node, 'json'); close(); } },
+          { label: 'XML', shortcut: 'X', onclick: () => { exportAs(node, 'xml'); close(); } },
+      ]},
+      { divider: true, label: 'Danger zone' },
+      { label: 'Delete', icon: '🗑️', className: 'danger',
+        isDisabled: !node.data?.canDelete,
+        onclick: () => { confirm(`Delete?`) && alert('Deleted!'); close(); } },
+    ];
   }
 </script>
 
@@ -489,39 +443,48 @@ The tree supports context menus with two approaches: callback-based (recommended
   idMember="path"
   pathMember="path"
   contextMenuCallback={createContextMenu}
-  contextMenuXOffset={8}
-  contextMenuYOffset={0}
 />
 ```
 
-#### Snippet-Based Context Menus
+#### Snippet + Component Context Menus
 
 ```svelte
-<Tree
-  {data}
-  idMember="path"
-  pathMember="path"
->
-  {#snippet contextMenu(node, closeMenu)}
-    <div class="context-menu-item" onclick={() => { alert(`Open ${node.data.name}`); closeMenu(); }}>
-      📂 Open
-    </div>
-    <div class="context-menu-divider"></div>
-    <div class="context-menu-item" onclick={() => { alert(`Delete ${node.data.name}`); closeMenu(); }}>
-      🗑️ Delete
-    </div>
+<script lang="ts">
+  import { Tree, ContextMenuItemC, ContextMenuDividerC } from '@keenmate/svelte-treeview';
+</script>
+
+<Tree {data} idMember="path" pathMember="path">
+  {#snippet contextMenu(node, close)}
+    <ContextMenuItemC label="Copy" icon="📋" shortcut="C"
+      onclick={() => { copy(node); close(); }} />
+    {#if node.data?.type === 'folder'}
+      <ContextMenuItemC label="Export As..." icon="📤">
+        <ContextMenuItemC label="JSON" shortcut="J"
+          onclick={() => { exportAs(node, 'json'); close(); }} />
+        <ContextMenuItemC label="XML" shortcut="X"
+          onclick={() => { exportAs(node, 'xml'); close(); }} />
+      </ContextMenuItemC>
+    {/if}
+    <ContextMenuDividerC label="Danger zone" />
+    <ContextMenuItemC label="Delete" icon="🗑️" className="danger"
+      isDisabled={!!node.data?.readonly}
+      onclick={() => { del(node); close(); }} />
   {/snippet}
 </Tree>
 ```
 
 #### Context Menu Features
 
-- **Dynamic menus**: Generate menu items based on node properties
-- **Icons and dividers**: Visual organization and identification
-- **Disabled states**: Context-sensitive menu availability
+- **Unified types**: `ContextMenuItem`, `ContextMenuDivider`, `ContextMenuEntry` shared across svelte-treeview and canvas-tree
+- **Keyboard shortcuts**: `shortcut` field renders a hint and activates on keypress when menu is open (supports `Ctrl+`, `Shift+`, `Alt+` modifiers)
+- **Submenus**: `children` array opens nested menus on hover
+- **Named dividers**: `{ divider: true, label: 'Section' }` renders as `---- Section ----`
+- **Visibility control**: `isVisible: false` hides items (callback approach); snippet approach uses `{#if}`
+- **Flexible styling**: `className="danger"` or any custom CSS class
+- **Dynamic menus**: Generate items based on node properties
+- **Icons and disabled states**: Visual organization and context-sensitive availability
 - **Position offset**: `contextMenuXOffset`/`contextMenuYOffset` for cursor clearance
-- **Auto-close**: Closes on scroll, click outside, or programmatically
-- **Type safety**: Full TypeScript support with `ContextMenuItem` interface
+- **Auto-close**: Closes on scroll, click outside, Escape key, or programmatically
 
 ## Styling and Customization
 
@@ -625,12 +588,11 @@ The component includes several pre-built classes for styling selected nodes:
 | `data` | `T[]` | **required** | Array of data objects |
 | `idMember` | `string` | **required** | Property name for unique identifiers |
 | `pathMember` | `string` | **required** | Property name for hierarchical paths |
-| `sortCallback` | `(items: T[]) => T[]` | default sort | Function to sort items (optional) |
+| `sortCallback` | `(items: LTreeNode<T>[]) => LTreeNode<T>[]` | `undefined` | Function to sort tree nodes |
 
 #### Data Mapping Properties
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `treeId` | `string \| null` | `null` | Unique identifier for the tree |
 | `parentPathMember` | `string \| null` | `null` | Property name for parent path references |
 | `levelMember` | `string \| null` | `null` | Property name for node level |
 | `isExpandedMember` | `string \| null` | `null` | Property name for expanded state |
@@ -638,6 +600,9 @@ The component includes several pre-built classes for styling selected nodes:
 | `isDraggableMember` | `string \| null` | `null` | Property name for draggable state |
 | `isDropAllowedMember` | `string \| null` | `null` | Property name for drop allowed state |
 | `allowedDropPositionsMember` | `string \| null` | `null` | Property name for allowed drop positions array |
+| `isCollapsibleMember` | `string \| null` | `null` | Property name for collapsible state |
+| `getIsCollapsibleCallback` | `(node) => boolean` | `undefined` | Callback to determine if a node is collapsible |
+| `getIsDraggableCallback` | `(node) => boolean` | `undefined` | Callback to determine if a node is draggable |
 | `hasChildrenMember` | `string \| null` | `null` | Property name for children existence |
 | `isSorted` | `boolean \| null` | `null` | Whether items should be sorted |
 
@@ -648,7 +613,7 @@ The component includes several pre-built classes for styling selected nodes:
 | `getDisplayValueCallback` | `(node) => string` | `undefined` | Function to get display value |
 | `searchValueMember` | `string \| null` | `null` | Property name for search indexing |
 | `getSearchValueCallback` | `(node) => string` | `undefined` | Function to get search value |
-| `shouldUseInternalSearchIndex` | `boolean` | `false` | Enable built-in search functionality |
+| `shouldUseInternalSearchIndex` | `boolean` | `true` | Enable built-in search functionality |
 | `initializeIndexCallback` | `() => Index` | `undefined` | Function to initialize search index |
 | `searchText` | `string` (bindable) | `undefined` | Current search text |
 
@@ -677,9 +642,10 @@ Without both requirements, no search indexing will occur.
 |------|------|---------|-------------|
 | `expandLevel` | `number \| null` | `2` | Automatically expand nodes up to this level |
 | `shouldToggleOnNodeClick` | `boolean` | `true` | Toggle expansion on node click |
-| `orderMember` | `string \| null` | `null` | Property name for sort order (enables above/below positioning in drag-drop) |
+| `orderMember` | `string \| null` | `null` | Property name for sort order (enables before/after positioning in drag-drop) |
 | `indexerBatchSize` | `number \| null` | `25` | Number of nodes to process per batch during search indexing |
 | `indexerTimeout` | `number \| null` | `50` | Maximum time (ms) to wait for idle callback before forcing indexing |
+| `isLoading` | `boolean` | `false` | Show loading placeholder instead of tree content |
 | `shouldDisplayDebugInformation` | `boolean` | `false` | Show debug information panel with tree statistics and enable console debug logging |
 | `shouldDisplayContextMenuInDebugMode` | `boolean` | `false` | Display persistent context menu at fixed position for styling development |
 
@@ -690,7 +656,14 @@ Without both requirements, no search indexing will occur.
 | `progressiveRender` | `boolean` | `true` | Progressively render nodes in batches |
 | `initialBatchSize` | `number` | `20` | First batch size for progressive rendering |
 | `maxBatchSize` | `number` | `500` | Maximum batch size cap |
-| `flatIndentSize` | `string` | `'1.5rem'` | Indentation size per level in flat mode |
+| `virtualScroll` | `boolean` | `false` | Enable virtual scrolling (flat mode only, renders visible + overscan rows) |
+| `virtualRowHeight` | `number` | auto | Explicit row height in px (auto-measured from first row if not set) |
+| `virtualOverscan` | `number` | `5` | Extra rows rendered above/below viewport |
+| `virtualContainerHeight` | `string` | auto/`'400px'` | CSS height for scroll container (auto-detected from parent if not set) |
+| `isRendering` | `boolean` (bindable) | `false` | Whether the tree is currently rendering (useful for progress indicators) |
+| `onRenderStart` | `() => void` | `undefined` | Called when progressive rendering begins |
+| `onRenderProgress` | `(rendered: number, total: number) => void` | `undefined` | Called after each batch with progress info |
+| `onRenderComplete` | `() => void` | `undefined` | Called when progressive rendering finishes |
 
 #### Drag & Drop Properties
 | Prop | Type | Default | Description |
@@ -712,7 +685,7 @@ Without both requirements, no search indexing will occur.
 | `onNodeClicked` | `(node) => void` | `undefined` | Node click event handler |
 | `onNodeDragStart` | `(node, event) => void` | `undefined` | Drag start event handler |
 | `onNodeDragOver` | `(node, event) => void` | `undefined` | Drag over event handler |
-| `onNodeDrop` | `(dropNode, draggedNode, position, event, operation) => void` | `undefined` | Drop event handler. Position is `'above'`, `'below'`, or `'child'`. Operation is `'move'` or `'copy'` |
+| `onNodeDrop` | `(dropNode, draggedNode, position, event, operation) => void` | `undefined` | Drop event handler. `dropNode` can be `null` (e.g., drop on empty tree). Position is `'before'`, `'after'`, or `'child'`. Operation is `'move'` or `'copy'` |
 
 #### Visual Styling Properties
 | Prop | Type | Default | Description |
@@ -731,9 +704,10 @@ Without both requirements, no search indexing will occur.
 |---------|------------|-------------|
 | `nodeTemplate` | `(node)` | Custom node template |
 | `treeHeader` | | Tree header content |
-| `treeBody` | | Tree body content |
 | `treeFooter` | | Tree footer content |
-| `noDataFound` | | No data template |
+| `noDataFound` | | Content shown when tree has no data |
+| `dropPlaceholder` | | Content shown in empty drop target tree |
+| `loadingPlaceholder` | | Content shown while `isLoading` is true |
 | `contextMenu` | `(node, closeMenu)` | Context menu template |
 
 #### Public Methods
@@ -748,19 +722,31 @@ Without both requirements, no search indexing will occur.
 | `scrollToPath` | `path: string, options?: ScrollToPathOptions` | Scroll to and highlight a specific node |
 | `update` | `updates: Partial<Props>` | Programmatically update component props from external JavaScript |
 | `addNode` | `parentPath: string, data: T, pathSegment?: string` | Add a new node under the specified parent |
-| `moveNode` | `sourcePath: string, targetPath: string, position: 'above' \| 'below' \| 'child'` | Move a node to a new location |
+| `moveNode` | `sourcePath: string, targetPath: string, position: 'before' \| 'after' \| 'child'` | Move a node to a new location |
 | `removeNode` | `path: string, includeDescendants?: boolean` | Remove a node (and optionally its descendants) |
 | `getNodeByPath` | `path: string` | Get a node by its path |
 | `getChildren` | `parentPath: string` | Get direct children of a node |
 | `getSiblings` | `path: string` | Get siblings of a node (including itself) |
+| `updateNode` | `path: string, data: Partial<T>` | Update a node's data properties |
+| `copyNodeWithDescendants` | `sourcePath: string, targetPath: string, position: DropPosition` | Copy a node and its subtree to a new location |
+| `refreshNode` | `path: string` | Force re-render of a specific node |
+| `refreshSiblings` | `path: string` | Force re-render of a node's siblings |
+| `getExpandedPaths` | | Get array of all currently expanded node paths |
+| `setExpandedPaths` | `paths: string[]` | Restore expanded state from saved paths |
+| `getAllData` | | Get all tree data as a flat array |
+| `applyChanges` | | Apply pending changes and refresh the tree |
+| `closeContextMenu` | | Programmatically close the context menu |
 
 #### ScrollToPath Options
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `expand` | `boolean` | `true` | Automatically expand parent nodes to make target visible |
+| `expandTarget` | `boolean` | `false` | Also expand the target node itself (not just its ancestors) |
 | `highlight` | `boolean` | `true` | Apply temporary highlight animation to the target node |
 | `scrollOptions` | `ScrollIntoViewOptions` | `{ behavior: 'smooth', block: 'center' }` | Native browser scroll options |
+| `containerScroll` | `boolean` | `false` | Scroll only within nearest scrollable ancestor (prevents page scroll) |
+| `containerElement` | `HTMLElement` | `undefined` | Explicit scrollable container element to use for scrolling |
 
 **Usage Example:**
 ```typescript
@@ -776,6 +762,9 @@ await tree.scrollToPath('1.2.3', {
     block: 'start'
   }
 });
+
+// Scroll within a scrollable container (prevents page scroll)
+await tree.scrollToPath('1.2.3', { containerScroll: true });
 ```
 
 **Highlight Classes Example:**
@@ -939,7 +928,7 @@ const sortCallback = (items: LTreeNode<T>[]) => {
     }
 
     // Then sort by your custom criteria
-    return a.data.name.localeCompare(b.data.name);
+    return (a.data?.name ?? '').localeCompare(b.data?.name ?? '');
   });
 };
 ```
@@ -1010,36 +999,40 @@ interface InsertArrayResult<T> {
 
 The component is optimized for large datasets:
 
+- **Virtual Scroll**: Renders only visible rows (~50 DOM nodes) for trees with 50,000+ nodes
 - **Flat Rendering Mode**: Single `{#each}` loop instead of recursive components (default, ~12x faster initial render)
 - **Progressive Rendering**: Batched rendering prevents UI freeze during initial load
-- **Context-Based Callbacks**: Stable function references eliminate unnecessary re-renders
-- **LTree**: Efficient hierarchical data structure
 - **Async Search Indexing**: Uses `requestIdleCallback` for non-blocking search index building
-- **Accurate Search Results**: Search index only includes successfully inserted nodes
-- **Search Indexing**: Uses FlexSearch for fast search operations
+- **LTree**: Efficient hierarchical data structure with FlexSearch integration
 
 ### Performance Benchmarks (5500 nodes)
 
 | Operation | Time |
 |-----------|------|
-| Initial render | ~25ms |
+| Initial render (flat) | ~25ms |
+| Initial render (virtual) | ~5ms |
 | Expand/collapse | ~100-150ms |
 | Search filtering | <50ms |
+| insertArray | <100ms |
+
+### Virtual Scroll
 
-### v4.5+ Performance Improvements
+For trees with 10,000+ nodes, enable virtual scroll to keep DOM size constant:
 
-**Flat Rendering Mode** (default) - Renders all visible nodes in a single loop:
 ```svelte
 <Tree
   {data}
-  useFlatRendering={true}
-  progressiveRender={true}
+  virtualScroll={true}
+  virtualContainerHeight="500px"
+  virtualOverscan={5}
 />
 ```
 
-**Optimized `insertArray` algorithm** - Fixed O(n²) bottleneck. Now loads 17,000+ nodes in under 100ms.
+Virtual scroll auto-measures row height from the first rendered node. Override with `virtualRowHeight={32}` if needed. Requires flat rendering mode (the default).
+
+### Performance Logging
 
-**Performance Logging** - Built-in performance measurement for debugging:
+Built-in performance measurement for debugging:
 ```typescript
 import { enablePerfLogging } from '@keenmate/svelte-treeview';
 enablePerfLogging();
@@ -1052,32 +1045,12 @@ window.components['svelte-treeview'].perf.enable()
 
 ## CanvasTree (Canvas-Based Rendering)
 
-`CanvasTree` renders the tree on an HTML5 Canvas for high-performance visualization of large hierarchies. It supports multiple layout modes, keyboard navigation, drag & drop, and custom node rendering.
-
-### Layout Modes
-
-| Mode | Description |
-|------|-------------|
-| `tree` | Standard hierarchical tree (default) |
-| `balanced` | Root centered with two symmetric arms |
-| `fishbone` | Spine with alternating branches above/below |
-| `radial` | Star / concentric rings from center |
-| `box` | Space-filling treemap |
-
-### Fishbone Navigation
+Canvas rendering is available as a separate companion package: [`@keenmate/svelte-treeview-canvas`](https://github.com/keenmate/svelte-treeview-canvas)
 
-In fishbone layout, keyboard navigation follows the fishbone structure:
+It renders trees on HTML5 Canvas for high-performance visualization with multiple layout modes (tree, balanced, fishbone, radial, box), keyboard navigation, drag & drop, and custom node rendering. Install it separately:
 
-- **Left/Right**: Navigate between same-side nodes along the spine axis. Spine nodes stay on their side; branch nodes traverse same-depth peers across all spine branches.
-- **Up/Down**: Navigate parent/child within a branch. From spine nodes, enters branch children on the pressed side.
-- **Cross-spine** (optional): When `fishboneCrossNav={true}`, Up/Down crosses to the opposite side of the spine when no more nodes exist in the current direction.
-
-```svelte
-<CanvasTree
-  {data}
-  layoutMode="fishbone"
-  fishboneCrossNav={false}  <!-- default: stops at spine boundary -->
-/>
+```bash
+npm install @keenmate/svelte-treeview-canvas
 ```
 
 ## Development Setup & Contributing