@keenmate/svelte-treeview 4.8.0 → 5.0.0-rc02

package/ai/events-callbacks.txt

@@ -0,0 +1,382 @@
+EVENTS AND CALLBACKS
+====================
+
+CRITICAL: Event-driven architecture
+- Callbacks for user interactions
+- Callbacks for data transformation
+- Callbacks for drag and drop
+- All callbacks receive LTreeNode<T>
+
+NODE CLICK
+----------
+<Tree
+  onNodeClicked={(node) => {
+    console.log('Clicked:', node.data.name);
+    console.log('Path:', node.path);
+    console.log('Level:', node.level);
+  }}
+/>
+
+Toggle on click (default: true):
+<Tree shouldToggleOnNodeClick={false} />
+
+When false, clicks only select, don't expand/collapse.
+
+DRAG EVENTS
+-----------
+<Tree
+  onNodeDragStart={(node, event) => {
+    console.log('Started dragging:', node.data.name);
+    // Can modify event.dataTransfer here
+  }}
+
+  onNodeDragOver={(node, event) => {
+    console.log('Dragging over:', node.data.name);
+  }}
+
+  onNodeDrop={(dropNode, draggedNode, position, event, operation) => {
+    console.log('Dropped:', draggedNode.data.name);
+    console.log('Target:', dropNode?.data.name);
+    console.log('Position:', position);  // 'before', 'after', 'child'
+    console.log('Operation:', operation);  // 'move', 'copy'
+  }}
+/>
+
+BEFORE DROP CALLBACK
+--------------------
+Validate or modify drops before they happen:
+
+<Tree
+  beforeDropCallback={async (dropNode, draggedNode, position, event, operation) => {
+    // Cancel the drop
+    if (draggedNode.data.locked) {
+      return false;
+    }
+
+    // Show confirmation
+    if (!await confirm('Are you sure?')) {
+      return false;
+    }
+
+    // Modify position
+    if (position === 'child' && dropNode.data.type === 'file') {
+      return { position: 'after' };
+    }
+
+    // Modify operation
+    if (event.shiftKey) {
+      return { operation: 'copy' };
+    }
+
+    // Proceed normally
+    return true;
+  }}
+/>
+
+Return values:
+- false → Cancel drop
+- true / undefined → Proceed normally
+- { position: 'before'|'after'|'child' } → Override position
+- { operation: 'move'|'copy' } → Override operation
+- { position, operation } → Override both
+- Promise<...> → Async validation
+
+DISPLAY VALUE CALLBACK
+----------------------
+Compute display text dynamically:
+
+<Tree
+  getDisplayValueCallback={(node) => {
+    const item = node.data;
+    return `${item.firstName} ${item.lastName}`;
+  }}
+/>
+
+Complex example:
+<Tree
+  getDisplayValueCallback={(node) => {
+    const item = node.data;
+    const count = item.children?.length || 0;
+    const suffix = count > 0 ? ` (${count})` : '';
+    return `${item.name}${suffix}`;
+  }}
+/>
+
+SEARCH VALUE CALLBACK
+---------------------
+Control what text gets indexed for search:
+
+<Tree
+  getSearchValueCallback={(node) => {
+    const item = node.data;
+    return `${item.name} ${item.email} ${item.tags.join(' ')}`;
+  }}
+/>
+
+ALLOWED DROP POSITIONS CALLBACK
+-------------------------------
+Control which drop positions are allowed per node:
+
+<Tree
+  getAllowedDropPositionsCallback={(node) => {
+    if (node.data.type === 'file') return ['before', 'after'];
+    if (node.data.type === 'trash') return ['child'];
+    return undefined;  // all positions
+  }}
+/>
+
+CONTEXT MENU CALLBACK
+---------------------
+Generate context menu items dynamically:
+
+<Tree
+  contextMenuCallback={(node, closeMenuCallback) => {
+    return [
+      {
+        icon: '📂',
+        title: 'Open',
+        callback: () => {
+          openItem(node.data);
+          closeMenuCallback();
+        }
+      },
+      { isDivider: true },
+      {
+        icon: '🗑️',
+        title: 'Delete',
+        isDisabled: node.data.isProtected,
+        callback: async () => {
+          if (await confirmDelete()) {
+            deleteItem(node.data);
+            closeMenuCallback();
+          }
+        }
+      }
+    ];
+  }}
+/>
+
+SORT CALLBACK
+-------------
+Custom sorting for tree display:
+
+<Tree
+  sortCallback={(nodes) => {
+    return nodes.sort((a, b) => {
+      // Sort by level first (required for proper tree construction)
+      const aLevel = a.path.split('.').length;
+      const bLevel = b.path.split('.').length;
+      if (aLevel !== bLevel) return aLevel - bLevel;
+
+      // Then by your criteria
+      return (a.data?.name ?? '').localeCompare(b.data?.name ?? '');
+    });
+  }}
+/>
+
+INITIALIZE INDEX CALLBACK
+-------------------------
+Custom FlexSearch index configuration:
+
+<Tree
+  initializeIndexCallback={() => {
+    return new Index({
+      tokenize: 'forward',
+      resolution: 9,
+      cache: true
+    });
+  }}
+/>
+
+BINDING VS CALLBACK
+-------------------
+Bindable props (two-way):
+- searchText
+- selectedNode
+- insertResult
+
+Callback props (one-way notification):
+- onNodeClicked
+- onNodeDrop
+- onNodeDragStart
+- onNodeDragOver
+
+Example combining both:
+
+<script>
+  let selectedNode = $state(null);
+
+  function handleClick(node) {
+    // Called in addition to selectedNode update
+    console.log('Clicked:', node.path);
+    analytics.track('node_click', { path: node.path });
+  }
+</script>
+
+<Tree
+  bind:selectedNode
+  onNodeClicked={handleClick}
+/>
+
+CALLBACK SIGNATURES
+-------------------
+onNodeClicked:
+(node: LTreeNode<T>) => void
+
+onNodeDragStart:
+(node: LTreeNode<T>, event: DragEvent) => void
+
+onNodeDragOver:
+(node: LTreeNode<T>, event: DragEvent) => void
+
+onNodeDrop:
+(
+  dropNode: LTreeNode<T> | null,
+  draggedNode: LTreeNode<T>,
+  position: 'before' | 'after' | 'child',
+  event: DragEvent,
+  operation: 'move' | 'copy'
+) => void
+
+beforeDropCallback:
+(
+  dropNode: LTreeNode<T> | null,
+  draggedNode: LTreeNode<T>,
+  position: 'before' | 'after' | 'child',
+  event: DragEvent,
+  operation: 'move' | 'copy'
+) => boolean | { position?, operation? } | Promise<...>
+
+getDisplayValueCallback:
+(node: LTreeNode<T>) => string
+
+getSearchValueCallback:
+(node: LTreeNode<T>) => string
+
+getAllowedDropPositionsCallback:
+(node: LTreeNode<T>) => DropPosition[] | null | undefined
+
+contextMenuCallback:
+(node: LTreeNode<T>, closeMenu: () => void) => ContextMenuItem[]
+
+sortCallback:
+(nodes: LTreeNode<T>[]) => LTreeNode<T>[]
+
+initializeIndexCallback:
+() => Index
+
+ASYNC CALLBACKS
+---------------
+These callbacks support async/Promise:
+
+- beforeDropCallback (awaited before drop)
+- contextMenuCallback item callbacks (individual actions)
+
+Example async beforeDropCallback:
+beforeDropCallback={async (drop, drag, pos) => {
+  const allowed = await checkPermission(drag.data);
+  return allowed;
+}}
+
+Example async context menu:
+{
+  title: 'Save',
+  callback: async () => {
+    await saveToServer();
+    closeMenu();
+  }
+}
+
+ERROR HANDLING
+--------------
+Handle errors in async callbacks:
+
+beforeDropCallback={async (drop, drag, pos) => {
+  try {
+    await validateMove(drag, drop);
+    return true;
+  } catch (error) {
+    showError(error.message);
+    return false;
+  }
+}}
+
+Context menu with error handling:
+{
+  title: 'Delete',
+  callback: async () => {
+    try {
+      await deleteItem(node.data);
+      closeMenu();
+    } catch (error) {
+      showError('Failed to delete');
+      // Menu stays open
+    }
+  }
+}
+
+CALLBACK PRIORITY
+-----------------
+When both member and callback are set, callback wins:
+
+getDisplayValueCallback > displayValueMember
+
+<Tree
+  displayValueMember="name"  // Ignored
+  getDisplayValueCallback={(n) => n.data.title}  // Used
+/>
+
+COMMON PATTERNS
+---------------
+Selection tracking:
+<script>
+  let history = $state([]);
+</script>
+
+<Tree
+  onNodeClicked={(node) => {
+    history = [...history, node.path];
+  }}
+/>
+
+Prevent certain drops:
+<Tree
+  beforeDropCallback={(drop, drag) => {
+    // Prevent dropping folders into files
+    if (drag.data.type === 'folder' && drop?.data.type === 'file') {
+      showError('Cannot drop folder into file');
+      return false;
+    }
+    return true;
+  }}
+/>
+
+Analytics integration:
+<Tree
+  onNodeClicked={(node) => {
+    analytics.track('tree_click', {
+      path: node.path,
+      type: node.data.type
+    });
+  }}
+  onNodeDrop={(drop, drag, pos) => {
+    analytics.track('tree_drop', {
+      from: drag.path,
+      to: drop?.path,
+      position: pos
+    });
+  }}
+/>
+
+BEST PRACTICES
+--------------
+✅ Use callbacks for side effects (logging, analytics)
+✅ Use bindings for state synchronization
+✅ Handle errors in async callbacks
+✅ Return early from beforeDropCallback for validation
+✅ Close context menu after successful action
+
+❌ Don't modify node data directly in callbacks
+❌ Don't do heavy computation in callbacks
+❌ Don't forget error handling in async callbacks
+❌ Don't block UI with sync operations

package/ai/import-patterns.txt

@@ -0,0 +1,271 @@
+IMPORT PATTERNS
+===============
+
+CRITICAL: Always import styles along with the component
+- Component has no embedded styles
+- Styles must be imported separately
+- Both CSS and SCSS versions available
+
+BASIC IMPORT
+------------
+// Component import
+import { Tree } from '@keenmate/svelte-treeview';
+
+// Style import (pick one)
+import '@keenmate/svelte-treeview/styles.css';   // Compiled CSS
+import '@keenmate/svelte-treeview/styles.scss';  // SCSS source
+
+COMPONENT EXPORTS
+-----------------
+Named exports from the package:
+
+// Main component
+import { Tree } from '@keenmate/svelte-treeview';
+
+// Types
+import type {
+  LTreeNode,
+  Ltree,
+  ContextMenuItem,
+  DropPosition,
+  InsertArrayResult,
+  NodeCallbacks,
+  NodeConfig
+} from '@keenmate/svelte-treeview';
+
+// Logging utilities
+import {
+  enableLogging,
+  disableLogging,
+  setLogLevel,
+  setCategoryLevel,
+  enablePerfLogging,
+  disablePerfLogging,
+  setPerfThreshold
+} from '@keenmate/svelte-treeview';
+
+STYLE IMPORTS
+-------------
+Option 1: In JavaScript entry point
+// main.ts or main.js
+import '@keenmate/svelte-treeview/styles.css';
+
+Option 2: In root layout (SvelteKit)
+// +layout.svelte
+<script>
+  import '@keenmate/svelte-treeview/styles.css';
+</script>
+
+Option 3: In component file
+// MyComponent.svelte
+<script>
+  import { Tree } from '@keenmate/svelte-treeview';
+  import '@keenmate/svelte-treeview/styles.css';
+</script>
+
+Option 4: In Svelte style block (SCSS only)
+<style lang="scss">
+  @import '@keenmate/svelte-treeview/styles.scss';
+</style>
+
+SCSS CUSTOMIZATION
+------------------
+Override variables before importing:
+
+<style lang="scss">
+  // Override variables
+  $tree-node-indent-per-level: 1.5rem;
+  $ltree-primary: #6366f1;
+
+  // Then import
+  @import '@keenmate/svelte-treeview/styles.scss';
+</style>
+
+TYPE IMPORTS
+------------
+Import types for TypeScript:
+
+import type { LTreeNode } from '@keenmate/svelte-treeview';
+
+interface MyItem {
+  id: string;
+  path: string;
+  name: string;
+}
+
+let selectedNode: LTreeNode<MyItem> | null = $state(null);
+
+Full type imports:
+
+import type {
+  LTreeNode,           // Tree node interface
+  Ltree,               // Tree instance interface
+  ContextMenuItem,     // Context menu item
+  DropPosition,        // 'before' | 'after' | 'child'
+  InsertArrayResult,   // Insert operation result
+  NodeCallbacks,       // Event callback types
+  NodeConfig           // Node configuration types
+} from '@keenmate/svelte-treeview';
+
+LOGGING IMPORTS
+---------------
+Debug and performance logging:
+
+// Enable all logging
+import { enableLogging } from '@keenmate/svelte-treeview';
+enableLogging();
+
+// Category-specific logging
+import { setCategoryLevel } from '@keenmate/svelte-treeview';
+setCategoryLevel('LTREE:DRAG', 'debug');
+setCategoryLevel('LTREE:RENDER', 'debug');
+
+// Performance logging
+import { enablePerfLogging, setPerfThreshold } from '@keenmate/svelte-treeview';
+enablePerfLogging();
+setPerfThreshold(100); // Only log operations > 100ms
+
+Log categories:
+- LTREE:INIT - Initialization
+- LTREE:DATA - Data operations
+- LTREE:RENDER - Rendering
+- LTREE:INDEX - Search indexing
+- LTREE:DRAG - Drag and drop
+- LTREE:UI - User interactions
+
+GLOBAL API
+----------
+Access from browser console:
+
+// Check version
+window.components['svelte-treeview'].version()
+
+// Enable logging from console
+window.components['svelte-treeview'].logging.enableLogging()
+
+// Performance logging
+window.components['svelte-treeview'].perf.enable()
+
+// Get package info
+window.components['svelte-treeview'].config
+
+SVELTEKIT IMPORT
+----------------
+// +page.svelte
+<script lang="ts">
+  import { Tree } from '@keenmate/svelte-treeview';
+  import type { LTreeNode } from '@keenmate/svelte-treeview';
+
+  interface Item {
+    id: string;
+    path: string;
+    name: string;
+  }
+
+  let data: Item[] = $state([]);
+  let selectedNode: LTreeNode<Item> | null = $state(null);
+</script>
+
+<Tree
+  {data}
+  idMember="id"
+  pathMember="path"
+  bind:selectedNode
+/>
+
+// +layout.svelte (for global styles)
+<script>
+  import '@keenmate/svelte-treeview/styles.css';
+</script>
+
+<slot />
+
+VITE + SVELTE IMPORT
+--------------------
+// main.ts
+import './app.css'
+import '@keenmate/svelte-treeview/styles.css';
+import App from './App.svelte'
+
+const app = new App({
+  target: document.getElementById('app')!,
+})
+
+export default app
+
+// App.svelte
+<script lang="ts">
+  import { Tree } from '@keenmate/svelte-treeview';
+</script>
+
+DYNAMIC IMPORT
+--------------
+For code splitting:
+
+<script>
+  import { onMount } from 'svelte';
+
+  let Tree;
+
+  onMount(async () => {
+    const module = await import('@keenmate/svelte-treeview');
+    Tree = module.Tree;
+
+    // Import styles dynamically
+    await import('@keenmate/svelte-treeview/styles.css');
+  });
+</script>
+
+{#if Tree}
+  <svelte:component this={Tree} {data} ... />
+{/if}
+
+PACKAGE STRUCTURE
+-----------------
+@keenmate/svelte-treeview/
+├── dist/
+│   ├── index.js          # Main entry (ESM)
+│   ├── index.d.ts        # TypeScript declarations
+│   ├── styles.css        # Compiled CSS
+│   └── styles.scss       # SCSS source
+└── package.json
+
+PEER DEPENDENCIES
+-----------------
+Required:
+- svelte: ^5.0.0
+
+Optional:
+- flexsearch: ^0.8.205 (for search functionality)
+
+If using search features:
+npm install flexsearch
+
+TROUBLESHOOTING
+---------------
+"Module not found" error:
+✅ npm install @keenmate/svelte-treeview
+✅ Check node_modules exists
+
+"Tree is not defined":
+✅ import { Tree } from '@keenmate/svelte-treeview';
+❌ import Tree from '@keenmate/svelte-treeview';
+
+No styles showing:
+✅ import '@keenmate/svelte-treeview/styles.css';
+✅ Check import is actually executed
+
+TypeScript errors:
+✅ import type { LTreeNode } from '@keenmate/svelte-treeview';
+✅ Check tsconfig.json has proper module resolution
+
+BEST PRACTICES
+--------------
+✅ Import styles once at app root level
+✅ Use type imports for TypeScript
+✅ Use named exports (not default)
+✅ Import logging utilities only in development
+
+❌ Don't import styles multiple times
+❌ Don't use default imports
+❌ Don't forget peer dependencies