@keenmate/svelte-treeview 4.8.0 → 5.0.0-rc02

package/ai/performance.txt

@@ -0,0 +1,349 @@
+PERFORMANCE
+===========
+
+CRITICAL: Use $state.raw() for large datasets
+- Svelte 5's $state() creates deep proxies
+- With 1000+ items, this causes massive slowdown
+- $state.raw() avoids proxy overhead
+
+$STATE.RAW() REQUIREMENT
+------------------------
+❌ SLOW - 5000x slower with large datasets:
+let treeData = $state<TreeNode[]>([]);
+
+✅ FAST - Items remain plain objects:
+let treeData = $state.raw<TreeNode[]>([]);
+
+Why it matters:
+- $state() creates Proxy for every nested object
+- Tree's insertArray() accesses multiple properties per item
+- 8000 items × 10 properties = 80,000 proxy operations
+- Proxy overhead: ~2.2ms per item vs ~0.0004ms plain
+
+Symptoms of wrong usage:
+- Tree takes 15-90+ seconds to render
+- Console shows "[Violation] 'message' handler took XXXXms"
+- Same data loads instantly in isolated test
+
+The fix does NOT affect reactivity:
+- Array changes still trigger updates
+- Only individual items lose deep reactivity
+- Tree doesn't need deep item reactivity
+
+FLAT RENDERING MODE
+-------------------
+Default mode (v4.6+) - significantly faster:
+
+<Tree useFlatRendering={true} />  <!-- Default -->
+
+Flat mode benefits:
+- Single {#each} loop instead of recursive components
+- ~12x faster initial render (300ms → 25ms for 5500 nodes)
+- Better memory usage
+
+Legacy recursive mode:
+<Tree useFlatRendering={false} />
+
+Use recursive mode only if:
+- Very small trees (<100 nodes)
+- Need {#key changeTracker} behavior
+
+PROGRESSIVE RENDERING
+---------------------
+Renders nodes in batches to prevent UI freeze:
+
+<Tree
+  progressiveRender={true}    <!-- Default -->
+  initialBatchSize={20}       <!-- First batch (instant) -->
+  maxBatchSize={500}          <!-- Maximum batch size -->
+/>
+
+Exponential batching:
+- First batch: 20 nodes (instant feedback)
+- Second batch: 40 nodes
+- Third batch: 80 nodes
+- Doubles until maxBatchSize (500)
+
+Result: UI stays responsive during large tree loads
+
+ASYNC SEARCH INDEXING
+---------------------
+Search indexing uses requestIdleCallback:
+
+<Tree
+  shouldUseInternalSearchIndex={true}
+  indexerBatchSize={25}   <!-- Nodes per idle callback -->
+  indexerTimeout={50}     <!-- Max wait before forcing -->
+/>
+
+Benefits:
+- Tree renders immediately
+- Indexing runs during browser idle time
+- Large datasets don't freeze UI
+
+Check indexing status:
+const stats = treeRef.statistics;
+console.log('Indexing:', stats.isIndexing);
+console.log('Pending:', stats.pendingIndexCount);
+
+VIRTUAL SCROLL MODE
+-------------------
+For very large trees (10,000+ nodes), virtual scroll only renders
+visible rows + overscan, keeping DOM size at ~50 nodes:
+
+<Tree
+  virtualScroll={true}
+  virtualContainerHeight="500px"   <!-- CSS height (auto-detected if not set) -->
+  virtualOverscan={5}              <!-- Extra rows above/below viewport -->
+/>
+
+How it works:
+- Fixed-height container with overflow-y: auto
+- Full-height spacer div for correct scrollbar proportions
+- translateY(offset) positions visible window
+- rAF-throttled scroll handler prevents excessive updates
+- Auto-measures row height from first rendered node
+
+Virtual scroll requires flat rendering (useFlatRendering=true, the default).
+
+scrollToPath in virtual mode:
+- Uses index-based scrolling (finds node in flat array)
+- Centers target in viewport
+- Waits for scroll + re-render (multiple rAF cycles)
+- Applies highlight with retry
+
+RENDERING MODE COMPARISON
+-------------------------
+| Mode | DOM Nodes | Best For |
+|------|-----------|----------|
+| Recursive | All nodes | Small trees (<100) |
+| Flat | All nodes | Medium trees (100-10K) |
+| Virtual | ~50 nodes | Large trees (10K+) |
+
+RENDER PROGRESS CALLBACKS
+-------------------------
+Monitor progressive rendering:
+
+<Tree
+  {data}
+  progressiveRender={true}
+  bind:isRendering
+  onRenderStart={() => console.log('Render started')}
+  onRenderProgress={(rendered, total) =>
+    console.log(`Rendered ${rendered}/${total}`)
+  }
+  onRenderComplete={() => console.log('Render complete')}
+/>
+
+isRendering is a bindable boolean — useful for showing spinners/progress bars.
+
+SORTING PERFORMANCE
+-------------------
+Level-first sorting is critical:
+
+// REQUIRED: Sort by level first
+sortCallback={(nodes) => {
+  return nodes.sort((a, b) => {
+    const aLevel = a.path.split('.').length;
+    const bLevel = b.path.split('.').length;
+    if (aLevel !== bLevel) return aLevel - bLevel;
+    return (a.data?.name ?? '').localeCompare(b.data?.name ?? '');
+  });
+}}
+
+For pre-sorted data (skip internal sort):
+<Tree isSorted={true} />
+
+PERFORMANCE LOGGING
+-------------------
+Enable performance measurements:
+
+import { enablePerfLogging, setPerfThreshold } from '@keenmate/svelte-treeview';
+
+enablePerfLogging();
+setPerfThreshold(100);  // Only log operations > 100ms
+
+Or from browser console:
+window.components['svelte-treeview'].perf.enable()
+
+Logged operations:
+- insertArray (conversion/sort/insert phases)
+- filterNodes
+- expandAll
+- collapseAll
+
+Output includes:
+- Duration
+- Item count
+- Per-item time
+- Items/sec throughput
+
+CATEGORY LOGGING
+----------------
+import { setCategoryLevel } from '@keenmate/svelte-treeview';
+
+// Enable specific categories
+setCategoryLevel('LTREE:RENDER', 'debug');
+setCategoryLevel('LTREE:DATA', 'debug');
+
+Categories:
+- LTREE:INIT - Initialization
+- LTREE:DATA - Data operations
+- LTREE:RENDER - Rendering
+- LTREE:INDEX - Search indexing
+- LTREE:DRAG - Drag and drop
+- LTREE:UI - User interactions
+
+BENCHMARKS
+----------
+Typical performance (5500 nodes):
+
+| Operation | Time |
+|-----------|------|
+| Initial render (flat) | ~25ms |
+| Initial render (recursive) | ~300ms |
+| Initial render (virtual) | ~5ms |
+| Expand/collapse | ~100-150ms |
+| Search filtering | <50ms |
+| insertArray | <100ms |
+
+MEMORY OPTIMIZATION
+-------------------
+For very large datasets (10,000+ nodes):
+
+1. Use $state.raw():
+let data = $state.raw<Item[]>([]);
+
+2. Enable progressive render:
+<Tree progressiveRender={true} />
+
+3. Limit initial expand:
+<Tree expandLevel={1} />
+
+4. Use virtual scrolling for 10K+ nodes:
+<Tree virtualScroll={true} virtualContainerHeight="500px" />
+
+AVOID O(n²) PATTERNS
+--------------------
+In sortCallback, avoid:
+
+❌ nodes.forEach(n => {
+  const siblings = nodes.filter(s => s.parentPath === n.parentPath);
+});
+
+✅ Pre-compute:
+const siblingMap = new Map();
+nodes.forEach(n => {
+  const parent = n.parentPath || '';
+  if (!siblingMap.has(parent)) siblingMap.set(parent, []);
+  siblingMap.get(parent).push(n);
+});
+
+BATCH DATA UPDATES
+------------------
+Instead of multiple small updates:
+
+❌ for (const item of items) {
+  data = [...data, item];  // Re-renders each time
+}
+
+✅ data = [...data, ...items];  // Single re-render
+
+EXPAND/COLLAPSE OPTIMIZATION
+----------------------------
+For large trees, be specific:
+
+// Slow: expands ALL nodes
+treeRef.expandAll();
+
+// Fast: expand specific subtree
+treeRef.expandAll('1.2');  // Only under 1.2
+
+// Fast: expand to level
+<Tree expandLevel={2} />
+
+SEARCH OPTIMIZATION
+-------------------
+Debounce search input:
+
+let inputValue = $state('');
+let searchText = $state('');
+let timer;
+
+function handleInput(e) {
+  inputValue = e.target.value;
+  clearTimeout(timer);
+  timer = setTimeout(() => {
+    searchText = inputValue;
+  }, 300);
+}
+
+Simplify search value callback:
+
+// Avoid heavy computation
+❌ getSearchValueCallback={(node) => {
+  return expensiveOperation(node.data);
+}}
+
+// Keep it simple
+✅ getSearchValueCallback={(node) => {
+  return `${node.data.name} ${node.data.email}`;
+}}
+
+DEBUG MODE OVERHEAD
+-------------------
+Disable in production:
+
+<Tree shouldDisplayDebugInformation={false} />
+
+Debug mode adds:
+- Statistics calculations
+- Console logging
+- Debug panel rendering
+
+COMMON PERFORMANCE ISSUES
+-------------------------
+Issue: Tree takes forever to render
+Fix: Use $state.raw() instead of $state()
+
+Issue: UI freezes during load
+Fix: Enable progressiveRender={true}
+
+Issue: Slow search
+Fix: Simplify getSearchValueCallback, use debouncing
+
+Issue: Slow sorting
+Fix: Avoid O(n²) patterns, use isSorted={true} for pre-sorted data
+
+Issue: Memory issues with huge datasets
+Fix: Limit expandLevel, use virtualScroll={true}
+
+PROFILING
+---------
+Use browser DevTools:
+
+1. Performance tab → Record
+2. Load tree or perform operation
+3. Look for long tasks
+
+Common bottlenecks:
+- Proxy access (use $state.raw())
+- Recursive component creation (use flat mode)
+- Search indexing (runs async, wait for completion)
+
+BEST PRACTICES
+--------------
+✅ Use $state.raw() for 1000+ items
+✅ Keep progressiveRender={true}
+✅ Keep useFlatRendering={true}
+✅ Limit expandLevel for large trees
+✅ Debounce search input
+✅ Use isSorted={true} for pre-sorted data
+✅ Use virtualScroll={true} for 10K+ nodes
+✅ Profile before optimizing
+
+❌ Don't use $state() for large datasets
+❌ Don't disable progressive rendering
+❌ Don't expand all levels for large trees
+❌ Don't do heavy computation in callbacks
+❌ Don't block UI with sync operations

package/ai/search-features.txt

@@ -0,0 +1,359 @@
+SEARCH FEATURES
+===============
+
+CRITICAL: Search requires explicit configuration
+- Set shouldUseInternalSearchIndex={true}
+- Provide searchValueMember OR getSearchValueCallback
+- Optional: FlexSearch for advanced search
+
+BASIC SEARCH SETUP
+------------------
+<script>
+  let searchText = $state('');
+</script>
+
+<input bind:value={searchText} placeholder="Search..." />
+
+<Tree
+  {data}
+  idMember="id"
+  pathMember="path"
+  bind:searchText
+  shouldUseInternalSearchIndex={true}
+  searchValueMember="name"
+/>
+
+SEARCH VALUE CONFIGURATION
+--------------------------
+What text gets indexed for search:
+
+// Simple: use a property
+<Tree searchValueMember="name" />
+
+// Complex: use callback for computed values
+<Tree
+  getSearchValueCallback={(node) => {
+    const item = node.data;
+    return `${item.name} ${item.description} ${item.tags.join(' ')}`;
+  }}
+/>
+
+ASYNC SEARCH INDEXING
+---------------------
+IMPORTANT: Search indexing happens asynchronously
+
+- Tree renders immediately
+- Indexing runs during browser idle time
+- Uses requestIdleCallback (or setTimeout fallback)
+- Large datasets won't freeze UI
+
+Check indexing status:
+const stats = treeRef.statistics;
+console.log('Is indexing:', stats.isIndexing);
+console.log('Pending:', stats.pendingIndexCount);
+
+INDEXER CONFIGURATION
+---------------------
+<Tree
+  indexerBatchSize={25}   <!-- Nodes per batch (default: 25) -->
+  indexerTimeout={50}     <!-- Max wait time ms (default: 50) -->
+/>
+
+indexerBatchSize:
+- Lower (10-25): Smoother UI, slower indexing
+- Higher (50-100): Faster indexing, brief UI pauses
+
+indexerTimeout:
+- Lower (25-50ms): More responsive indexing
+- Higher (100-200ms): More genuine idle periods
+
+FILTER VS SEARCH
+----------------
+filterNodes() - Hides non-matching nodes in tree display
+
+searchText binding uses filterNodes internally:
+<Tree bind:searchText ... />
+
+searchNodes() - Returns matching nodes without filtering
+
+<script>
+  function search(query) {
+    const results = treeRef.searchNodes(query);
+    console.log('Found:', results.length, 'nodes');
+    return results;
+  }
+</script>
+
+FLEXSEARCH OPTIONS
+------------------
+Both methods accept FlexSearch options:
+
+// Search with options
+const results = treeRef.searchNodes('query', {
+  suggest: true,      // Enable suggestions for typos
+  limit: 10,          // Max results
+  threshold: 0.8,     // Similarity threshold
+  bool: 'and'         // AND logic for multiple terms
+});
+
+// Filter with options
+treeRef.filterNodes('query', {
+  suggest: true,
+  limit: 50
+});
+
+SEARCH RESULTS NAVIGATION
+-------------------------
+<script>
+  let searchText = $state('');
+  let results = $state([]);
+  let currentIndex = $state(0);
+  let treeRef;
+
+  $effect(() => {
+    if (searchText) {
+      results = treeRef.searchNodes(searchText);
+      currentIndex = 0;
+      if (results.length > 0) {
+        goToResult(0);
+      }
+    }
+  });
+
+  async function goToResult(index) {
+    currentIndex = index;
+    await treeRef.scrollToPath(results[index].path, {
+      expand: true,
+      highlight: true,
+      containerScroll: true
+    });
+  }
+
+  function next() {
+    const nextIndex = (currentIndex + 1) % results.length;
+    goToResult(nextIndex);
+  }
+
+  function prev() {
+    const prevIndex = (currentIndex - 1 + results.length) % results.length;
+    goToResult(prevIndex);
+  }
+</script>
+
+<input bind:value={searchText} />
+<span>{currentIndex + 1} of {results.length}</span>
+<button onclick={prev}>Prev</button>
+<button onclick={next}>Next</button>
+
+CLEAR SEARCH
+------------
+// Clear search text (shows all nodes)
+searchText = '';
+
+// Or programmatically
+treeRef.filterNodes('');
+
+CUSTOM SEARCH INDEX
+-------------------
+Initialize your own FlexSearch index:
+
+<script>
+  import { Index } from 'flexsearch';
+
+  function initializeIndex() {
+    return new Index({
+      tokenize: 'forward',
+      resolution: 9,
+      cache: true
+    });
+  }
+</script>
+
+<Tree
+  initializeIndexCallback={initializeIndex}
+  shouldUseInternalSearchIndex={true}
+  searchValueMember="name"
+/>
+
+SEARCH WITHOUT INTERNAL INDEX
+-----------------------------
+Handle search externally:
+
+<script>
+  let data = $state.raw([...]);
+  let filteredData = $state.raw([...]);
+  let searchText = $state('');
+
+  $effect(() => {
+    if (searchText) {
+      filteredData = data.filter(item =>
+        item.name.toLowerCase().includes(searchText.toLowerCase())
+      );
+    } else {
+      filteredData = data;
+    }
+  });
+</script>
+
+<input bind:value={searchText} />
+<Tree data={filteredData} ... />
+
+Note: This approach loses the tree hierarchy when filtering
+
+SEARCH HIGHLIGHT
+----------------
+Highlight matching text in node template:
+
+<Tree {data} bind:searchText>
+  {#snippet nodeTemplate(node)}
+    {@html highlightMatch(node.data.name, searchText)}
+  {/snippet}
+</Tree>
+
+<script>
+  function highlightMatch(text, query) {
+    if (!query) return text;
+    const regex = new RegExp(`(${escapeRegex(query)})`, 'gi');
+    return text.replace(regex, '<mark>$1</mark>');
+  }
+
+  function escapeRegex(string) {
+    return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }
+</script>
+
+SEARCH DEBOUNCING
+-----------------
+Debounce search input for better performance:
+
+<script>
+  let inputValue = $state('');
+  let searchText = $state('');
+  let debounceTimer;
+
+  function handleInput(e) {
+    inputValue = e.target.value;
+    clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+      searchText = inputValue;
+    }, 300);
+  }
+</script>
+
+<input value={inputValue} oninput={handleInput} />
+<Tree bind:searchText ... />
+
+SEARCH STATISTICS
+-----------------
+Track search results:
+
+const stats = treeRef.statistics;
+console.log('Total nodes:', stats.nodeCount);
+console.log('Filtered visible:', stats.filteredNodeCount);
+
+// After search
+$effect(() => {
+  if (searchText) {
+    console.log(`Showing ${stats.filteredNodeCount} of ${stats.nodeCount}`);
+  }
+});
+
+MULTIPLE SEARCH FIELDS
+----------------------
+Index multiple properties:
+
+<Tree
+  getSearchValueCallback={(node) => {
+    const item = node.data;
+    return [
+      item.name,
+      item.email,
+      item.department,
+      item.tags.join(' ')
+    ].join(' ');
+  }}
+/>
+
+SEARCH WITH EMPTY TREE
+----------------------
+Handle no results state:
+
+<Tree {data} bind:searchText>
+  {#snippet noDataFound()}
+    {#if searchText}
+      <p>No results for "{searchText}"</p>
+    {:else}
+      <p>No items available</p>
+    {/if}
+  {/snippet}
+</Tree>
+
+COMMON SEARCH PATTERNS
+----------------------
+File search:
+<Tree
+  searchValueMember="name"
+  getSearchValueCallback={(node) =>
+    `${node.data.name} ${node.data.path} ${node.data.extension}`
+  }
+/>
+
+User search:
+<Tree
+  getSearchValueCallback={(node) =>
+    `${node.data.firstName} ${node.data.lastName} ${node.data.email}`
+  }
+/>
+
+Product search:
+<Tree
+  getSearchValueCallback={(node) =>
+    `${node.data.name} ${node.data.sku} ${node.data.category} ${node.data.description}`
+  }
+/>
+
+DEBUGGING SEARCH
+----------------
+Enable search indexing logs:
+
+import { setCategoryLevel } from '@keenmate/svelte-treeview';
+setCategoryLevel('LTREE:INDEX', 'debug');
+
+// Console shows:
+// - Indexer initialization
+// - Queue management
+// - Batch processing
+// - Indexing completion
+
+Check index status:
+console.log('Stats:', treeRef.statistics);
+
+BEST PRACTICES
+--------------
+✅ Set shouldUseInternalSearchIndex={true}
+✅ Provide searchValueMember or getSearchValueCallback
+✅ Use debouncing for search input
+✅ Handle loading state during indexing
+✅ Provide feedback for no results
+
+❌ Don't search before indexing completes
+❌ Don't use heavy callbacks (slows indexing)
+❌ Don't forget to clear search
+❌ Don't rely on immediate search after data load
+
+TROUBLESHOOTING
+---------------
+Search not working:
+✅ Check shouldUseInternalSearchIndex={true}
+✅ Check searchValueMember or getSearchValueCallback is set
+✅ Wait for indexing to complete (check statistics.isIndexing)
+
+Search slow:
+✅ Reduce indexerBatchSize
+✅ Simplify getSearchValueCallback
+✅ Use $state.raw() for large datasets
+
+No results found:
+✅ Check searchValueMember matches data property
+✅ Check getSearchValueCallback returns string
+✅ Check data actually contains search term