@keenmate/svelte-treeview 4.8.0 → 5.0.0-rc02

package/README.md

@@ -6,90 +6,38 @@ 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)**
 
-## New in v4.8: Virtual Scroll & Unified Rendering
+## v5.0: Core/Renderer Split + Virtual Scroll
 
-> [!NOTE]
-> **New virtual scroll mode renders only visible nodes — handle 50,000+ items without DOM bloat.**
+> [!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`.
 
-Three rendering modes, one consistent look:
+**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)
 
-| Mode | Best for | How it works |
-|------|----------|-------------|
-| **Recursive** | Small trees (<500 nodes) | Traditional nested Svelte components |
-| **Progressive** (default) | Medium trees (500–10,000) | Flat rendering with exponential batching |
-| **Virtual Scroll** | Large trees (10,000+) | Only visible rows + overscan are in the DOM |
+### Rendering Modes
 
-```svelte
-<Tree
-  {data}
-  virtualScroll={true}
-  virtualRowHeight={28}
-  virtualOverscan={5}
-  virtualContainerHeight="600px"
-/>
-```
-
-**Also in this release:**
-- **Search result navigation** — dual-mode filter/search with result counter, prev/next (Enter/Shift+Enter), round-robin cycling
-- **Floating drop zones auto-expand** when positions are restricted — pure CSS `:not(:has())`, zero JS overhead
-- **Cross-tree drop positioning fixed** — above/below placement now works correctly between trees
-- **Unified indentation & gaps** across all three rendering modes
-- **Drag & drop disabled by default** — set `dragDropMode="both"` to enable
-
-## v4.7: Per-Node Drop Position Restrictions
-
-> [!NOTE]
-> **You can now restrict which drop positions (above/below/child) are allowed per node.**
+| 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+) |
 
-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)
-}
-```
-
-## v4.6: Progressive Flat Rendering
-
-> [!NOTE]
-> **The tree now uses progressive flat rendering by default for significantly improved performance.**
-
-**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
-
-**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
@@ -175,14 +123,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}
@@ -297,13 +245,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>
@@ -323,16 +271,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
@@ -341,7 +289,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
   }
@@ -383,7 +331,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
@@ -424,7 +372,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');
     }
   }
 
@@ -443,7 +391,7 @@ 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
 
@@ -462,30 +410,30 @@ 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[] {
+  function createContextMenu(node, closeMenu: () => void): ContextMenuItem[] {
     const items: ContextMenuItem[] = [];
 
     // Always available
     items.push({
       icon: '📂',
       title: 'Open',
-      callback: () => alert(`Opening ${node.data.name}`)
+      callback: () => alert(`Opening ${node.data?.name}`)
     });
 
     // Conditional actions based on node data
-    if (node.data.canEdit) {
+    if (node.data?.canEdit) {
       items.push({
         icon: '✏️',
         title: 'Edit',
-        callback: () => alert(`Editing ${node.data.name}`)
+        callback: () => alert(`Editing ${node.data?.name}`)
       });
     }
 
-    if (node.data.canDelete) {
+    if (node.data?.canDelete) {
       items.push({
         icon: '🗑️',
         title: 'Delete',
-        callback: () => confirm(`Delete ${node.data.name}?`) && alert('Deleted!')
+        callback: () => confirm(`Delete ${node.data?.name}?`) && alert('Deleted!')
       });
     }
 
@@ -523,11 +471,11 @@ The tree supports context menus with two approaches: callback-based (recommended
   pathMember="path"
 >
   {#snippet contextMenu(node, closeMenu)}
-    <div class="context-menu-item" onclick={() => { alert(`Open ${node.data.name}`); 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(); }}>
+    <div class="context-menu-item" onclick={() => { alert(`Delete ${node.data?.name}`); closeMenu(); }}>
       🗑️ Delete
     </div>
   {/snippet}
@@ -645,12 +593,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 |
@@ -658,6 +605,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 |
 
@@ -668,7 +618,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 |
 
@@ -697,9 +647,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 |
 
@@ -710,6 +661,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 |
+| `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 |
@@ -731,7 +690,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 |
@@ -750,9 +709,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
@@ -767,19 +727,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
@@ -795,6 +767,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:**
@@ -958,7 +933,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 ?? '');
   });
 };
 ```
@@ -1029,36 +1004,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();
@@ -1069,6 +1048,16 @@ window.components['svelte-treeview'].perf.enable()
 
 **Important**: See the [$state.raw() tip](#quick-start) above - using `$state()` instead of `$state.raw()` for tree data can cause 5,000x slowdown!
 
+## CanvasTree (Canvas-Based Rendering)
+
+Canvas rendering is available as a separate companion package: [`@keenmate/svelte-treeview-canvas`](https://github.com/keenmate/svelte-treeview-canvas)
+
+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:
+
+```bash
+npm install @keenmate/svelte-treeview-canvas
+```
+
 ## Development Setup & Contributing
 
 For developers working on the project, you can use either standard npm commands or the provided Makefile: