@keenmate/svelte-treeview 4.8.0 → 5.0.0-rc02

package/ai/basic-setup.txt

@@ -0,0 +1,336 @@
+BASIC SETUP
+===========
+
+CRITICAL: This is a Svelte 5 component using runes
+- Requires Svelte 5.0.0 or higher
+- Uses $state, $derived, $effect runes
+- NOT compatible with Svelte 4 or earlier
+- Works with SvelteKit, Vite, or any Svelte 5 setup
+
+INSTALLATION
+------------
+npm install @keenmate/svelte-treeview
+
+# Or yarn
+yarn add @keenmate/svelte-treeview
+
+# Or pnpm
+pnpm add @keenmate/svelte-treeview
+
+IMPORT STYLES
+-------------
+The component requires CSS to display correctly:
+
+// In your main.js/main.ts or +layout.svelte
+import '@keenmate/svelte-treeview/styles.css';
+
+// Or SCSS (if you have sass configured)
+import '@keenmate/svelte-treeview/styles.scss';
+
+MINIMAL EXAMPLE
+---------------
+<script lang="ts">
+  import { Tree } from '@keenmate/svelte-treeview';
+
+  const data = [
+    { id: '1', path: '1', name: 'Documents' },
+    { id: '1.1', path: '1.1', name: 'Projects' },
+    { id: '1.1.1', path: '1.1.1', name: 'Project A' },
+    { id: '2', path: '2', name: 'Pictures' }
+  ];
+</script>
+
+<Tree
+  {data}
+  idMember="id"
+  pathMember="path"
+  displayValueMember="name"
+/>
+
+REQUIRED PROPS
+--------------
+These props are required for the tree to work:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| data | T[] | Array of data objects |
+| idMember | string | Property name for unique ID |
+| pathMember | string | Property name for hierarchical path |
+
+RECOMMENDED PROPS
+-----------------
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| displayValueMember | string | null | Property for display text |
+| sortCallback | function | built-in | Custom sort function |
+| expandLevel | number | 2 | Auto-expand nodes to this depth |
+
+PATH STRUCTURE
+--------------
+CRITICAL: Data must use path-based hierarchy
+
+The path defines the tree structure:
+- Root level: "1", "2", "3"
+- Second level: "1.1", "1.2", "2.1"
+- Third level: "1.1.1", "1.2.1"
+
+Parent path is derived from child path:
+- "1.2.3" → parent is "1.2"
+- "1.2" → parent is "1"
+- "1" → no parent (root)
+
+Custom separators:
+<Tree treePathSeparator="/" ... />
+// Paths: "1/2/3", "files/docs/readme"
+
+BINDING SELECTED NODE
+---------------------
+<script>
+  let selectedNode = $state(null);
+</script>
+
+<Tree
+  {data}
+  idMember="id"
+  pathMember="path"
+  bind:selectedNode
+/>
+
+{#if selectedNode}
+  <p>Selected: {selectedNode.data.name}</p>
+{/if}
+
+BINDING SEARCH TEXT
+-------------------
+<script>
+  let searchText = $state('');
+</script>
+
+<input bind:value={searchText} placeholder="Search..." />
+
+<Tree
+  {data}
+  idMember="id"
+  pathMember="path"
+  bind:searchText
+  shouldUseInternalSearchIndex={true}
+  searchValueMember="name"
+/>
+
+CUSTOM NODE TEMPLATE
+--------------------
+<Tree
+  {data}
+  idMember="id"
+  pathMember="path"
+>
+  {#snippet nodeTemplate(node)}
+    <div class="custom-node">
+      <span class="icon">{node.data.icon}</span>
+      <span class="name">{node.data.name}</span>
+      {#if node.data.count}
+        <span class="badge">{node.data.count}</span>
+      {/if}
+    </div>
+  {/snippet}
+</Tree>
+
+IMPORTANT: The snippet name is nodeTemplate (not nodeContent)
+
+EXPAND/COLLAPSE CONTROL
+-----------------------
+Control initial expansion:
+
+<Tree
+  {data}
+  expandLevel={3}  <!-- Expand first 3 levels -->
+/>
+
+Programmatic control:
+
+<script>
+  let treeRef;
+</script>
+
+<Tree bind:this={treeRef} {data} ... />
+
+<button onclick={() => treeRef.expandAll()}>Expand All</button>
+<button onclick={() => treeRef.collapseAll()}>Collapse All</button>
+<button onclick={() => treeRef.expandNodes('1.2')}>Expand 1.2</button>
+
+CLICK HANDLING
+--------------
+<Tree
+  {data}
+  idMember="id"
+  pathMember="path"
+  onNodeClicked={(node) => {
+    console.log('Clicked:', node.data.name);
+    console.log('Path:', node.path);
+  }}
+/>
+
+Toggle on click (default true):
+<Tree shouldToggleOnNodeClick={false} ... />
+
+SCROLL TO NODE
+--------------
+<script>
+  let treeRef;
+
+  async function goToNode() {
+    await treeRef.scrollToPath('1.2.3', {
+      expand: true,      // Expand parents first
+      highlight: true,   // Highlight the node
+      containerScroll: true  // Scroll only within container
+    });
+  }
+</script>
+
+<Tree bind:this={treeRef} {data} ... />
+<button onclick={goToNode}>Go to 1.2.3</button>
+
+TREE STATISTICS
+---------------
+<script>
+  let treeRef;
+
+  function showStats() {
+    const stats = treeRef.statistics;
+    console.log('Total nodes:', stats.nodeCount);
+    console.log('Max depth:', stats.maxLevel);
+    console.log('Filtered:', stats.filteredNodeCount);
+    console.log('Indexing:', stats.isIndexing);
+  }
+</script>
+
+DEBUG MODE
+----------
+Enable debug panel and console logging:
+
+<Tree
+  {data}
+  shouldDisplayDebugInformation={true}
+/>
+
+Shows:
+- Tree ID
+- Node count
+- Max depth
+- Filtered count
+- Indexing status
+- Currently dragged node
+
+EMPTY STATE
+-----------
+Custom message when tree is empty:
+
+<Tree {data} ...>
+  {#snippet noDataFound()}
+    <div class="empty-state">
+      <p>No items found</p>
+      <button>Add First Item</button>
+    </div>
+  {/snippet}
+</Tree>
+
+LOADING STATE
+-------------
+Show a loading placeholder while data is being fetched:
+
+<Tree {data} isLoading={isLoading}>
+  {#snippet loadingPlaceholder()}
+    <div class="loading">Loading tree data...</div>
+  {/snippet}
+</Tree>
+
+DROP PLACEHOLDER
+----------------
+Custom placeholder for empty trees that accept drops:
+
+<Tree {data} dragDropMode="both">
+  {#snippet dropPlaceholder()}
+    <div class="drop-here">Drop items here to start</div>
+  {/snippet}
+</Tree>
+
+FRAMEWORK INTEGRATION
+---------------------
+SvelteKit:
+// +page.svelte
+<script>
+  import { Tree } from '@keenmate/svelte-treeview';
+  import '@keenmate/svelte-treeview/styles.css';
+</script>
+
+Vite + Svelte:
+// App.svelte
+<script>
+  import { Tree } from '@keenmate/svelte-treeview';
+</script>
+
+// main.js
+import '@keenmate/svelte-treeview/styles.css';
+
+COMMON SETUP PATTERNS
+---------------------
+File explorer:
+<Tree
+  {data}
+  idMember="id"
+  pathMember="path"
+  displayValueMember="name"
+  expandLevel={1}
+  treePathSeparator="/"
+/>
+
+Organization tree:
+<Tree
+  {data}
+  idMember="employeeId"
+  pathMember="orgPath"
+  displayValueMember="fullName"
+  expandLevel={3}
+/>
+
+With search and drag-drop:
+<Tree
+  {data}
+  idMember="id"
+  pathMember="path"
+  bind:searchText
+  shouldUseInternalSearchIndex={true}
+  searchValueMember="name"
+  dragOverNodeClass="ltree-dragover-glow"
+  onNodeDrop={handleDrop}
+/>
+
+BROWSER SUPPORT
+---------------
+Requires modern browsers:
+- Chrome/Edge 88+
+- Firefox 78+
+- Safari 14+
+
+No IE11 support (Svelte 5 requirement)
+
+CRITICAL REMINDERS
+------------------
+✅ Import styles (CSS or SCSS)
+✅ Use Svelte 5.0.0 or higher
+✅ Use path-based hierarchical data
+✅ Set idMember and pathMember
+✅ Use $state.raw() for large datasets (1000+ items)
+
+❌ Don't use with Svelte 4 or earlier
+❌ Don't forget to import styles
+❌ Don't use non-path-based data structures
+❌ Don't use $state() for large datasets (causes slowdown)
+
+NEXT STEPS
+----------
+- Custom data structure → data-handling.txt
+- Add drag and drop → drag-drop.txt
+- Add search → search-features.txt
+- Add context menu → context-menu.txt
+- Optimize performance → performance.txt

package/ai/context-menu.txt

@@ -0,0 +1,349 @@
+CONTEXT MENU
+============
+
+CRITICAL: Two approaches for context menus
+- Callback-based (recommended): contextMenuCallback prop
+- Snippet-based: contextMenu snippet
+- Both support dynamic items, icons, disabled states
+
+CALLBACK-BASED CONTEXT MENU
+---------------------------
+<script>
+  import type { ContextMenuItem, LTreeNode } from '@keenmate/svelte-treeview';
+
+  function createContextMenu(node: LTreeNode<MyItem>, closeMenuCallback: () => void): ContextMenuItem[] {
+    const items: ContextMenuItem[] = [];
+
+    // Basic item
+    items.push({
+      icon: '📂',
+      title: 'Open',
+      callback: () => alert(`Opening ${node.data.name}`)
+    });
+
+    // Conditional item
+    if (node.data.canEdit) {
+      items.push({
+        icon: '✏️',
+        title: 'Edit',
+        callback: () => editItem(node.data)
+      });
+    }
+
+    // Divider
+    items.push({ isDivider: true });
+
+    // Disabled item
+    items.push({
+      icon: '🗑️',
+      title: 'Delete',
+      isDisabled: !node.data.canDelete,
+      callback: () => deleteItem(node.data)
+    });
+
+    return items;
+  }
+</script>
+
+<Tree
+  {data}
+  contextMenuCallback={createContextMenu}
+/>
+
+CONTEXT MENU ITEM INTERFACE
+---------------------------
+interface ContextMenuItem {
+  icon?: string;           // Optional icon (emoji or text)
+  title: string;           // Menu item text
+  isDisabled?: boolean;    // Disable the item
+  callback: () => void | Promise<void>;  // Action
+  isDivider?: boolean;     // Render as divider
+  className?: string;      // Custom CSS class
+}
+
+SNIPPET-BASED CONTEXT MENU
+--------------------------
+<Tree {data}>
+  {#snippet contextMenu(node, closeMenu)}
+    <div class="ltree-context-menu-item" onclick={() => {
+      openItem(node.data);
+      closeMenu();
+    }}>
+      📂 Open
+    </div>
+
+    <div class="ltree-context-menu-divider"></div>
+
+    <div
+      class="ltree-context-menu-item"
+      class:ltree-context-menu-item-disabled={!node.data.canDelete}
+      onclick={() => {
+        if (node.data.canDelete) {
+          deleteItem(node.data);
+          closeMenu();
+        }
+      }}
+    >
+      🗑️ Delete
+    </div>
+  {/snippet}
+</Tree>
+
+POSITION OFFSET
+---------------
+Adjust menu position relative to cursor:
+
+<Tree
+  contextMenuCallback={createMenu}
+  contextMenuXOffset={8}   <!-- Horizontal offset (default: 8px) -->
+  contextMenuYOffset={0}   <!-- Vertical offset (default: 0px) -->
+/>
+
+CLOSE MENU CALLBACK
+-------------------
+Callback receives closeMenu function for programmatic control:
+
+function createContextMenu(node, closeMenuCallback) {
+  return [
+    {
+      title: 'Action',
+      callback: async () => {
+        const success = await doSomething();
+        if (success) {
+          closeMenuCallback();  // Close only on success
+        }
+      }
+    }
+  ];
+}
+
+<Tree contextMenuCallback={createContextMenu} />
+
+ASYNC CALLBACKS
+---------------
+Menu item callbacks can be async:
+
+{
+  title: 'Save to Server',
+  callback: async () => {
+    try {
+      await saveToServer(node.data);
+      showSuccess('Saved!');
+    } catch (error) {
+      showError('Failed to save');
+      // Menu stays open on error
+    }
+  }
+}
+
+CLOSE CONTEXT MENU PROGRAMMATICALLY
+-----------------------------------
+<script>
+  let treeRef;
+
+  function closeMenuExternally() {
+    treeRef.closeContextMenu();
+  }
+</script>
+
+<Tree bind:this={treeRef} ... />
+
+AUTO-CLOSE BEHAVIOR
+-------------------
+Context menu automatically closes on:
+- Click outside the menu
+- Scroll events (mouse wheel, scrollbar, touch)
+- Another right-click
+- Pressing Escape
+- Window resize
+
+CUSTOM ITEM STYLING
+-------------------
+Add custom classes to items:
+
+{
+  title: 'Delete',
+  className: 'text-danger',  // Your CSS class
+  callback: () => deleteItem()
+}
+
+Built-in CSS classes:
+- .ltree-context-menu - Menu container
+- .ltree-context-menu-item - Menu item
+- .ltree-context-menu-item-disabled - Disabled item
+- .ltree-context-menu-icon - Icon container
+- .ltree-context-menu-divider - Divider line
+
+CONDITIONAL MENUS
+-----------------
+Show different menus based on node type:
+
+function createContextMenu(node, closeMenuCallback) {
+  if (node.data?.type === 'folder') {
+    return [
+      { title: 'New File', callback: () => newFile(node) },
+      { title: 'New Folder', callback: () => newFolder(node) },
+      { isDivider: true },
+      { title: 'Rename', callback: () => rename(node) },
+      { title: 'Delete', callback: () => deleteFolder(node) }
+    ];
+  }
+
+  if (node.data?.type === 'file') {
+    return [
+      { title: 'Open', callback: () => openFile(node) },
+      { title: 'Download', callback: () => downloadFile(node) },
+      { isDivider: true },
+      { title: 'Rename', callback: () => rename(node) },
+      { title: 'Delete', callback: () => deleteFile(node) }
+    ];
+  }
+
+  return [];  // No menu
+}
+
+ICONS
+-----
+Icons can be:
+- Emoji: '📁', '✏️', '🗑️'
+- Text: 'Edit', '[X]'
+- Unicode: '\u{1F4C1}'
+
+Example with emojis:
+{
+  icon: '📂',
+  title: 'Open Folder',
+  callback: () => openFolder()
+}
+
+DIVIDERS
+--------
+Add visual separation:
+
+[
+  { title: 'Cut', callback: () => cut() },
+  { title: 'Copy', callback: () => copy() },
+  { title: 'Paste', callback: () => paste() },
+  { isDivider: true },  // <-- Divider here
+  { title: 'Delete', callback: () => del() }
+]
+
+DISABLED ITEMS
+--------------
+Disable based on conditions:
+
+{
+  title: 'Paste',
+  isDisabled: clipboard.isEmpty(),
+  callback: () => paste()
+}
+
+{
+  title: 'Delete',
+  isDisabled: node.data.isReadOnly,
+  callback: () => deleteItem()
+}
+
+DEBUG MODE
+----------
+For CSS development, show menu persistently:
+
+<Tree
+  contextMenuCallback={createMenu}
+  shouldDisplayContextMenuInDebugMode={true}
+  shouldDisplayDebugInformation={true}
+/>
+
+Debug mode:
+- Shows menu at fixed position (200px right, 100px down from tree)
+- Uses second node (or first if only one)
+- Menu stays visible for styling
+
+COMMON PATTERNS
+---------------
+File explorer menu:
+function createMenu(node, closeMenuCallback) {
+  const items = [];
+
+  if (node.data?.type === 'folder') {
+    items.push(
+      { icon: '📄', title: 'New File', callback: () => newFile(node) },
+      { icon: '📁', title: 'New Folder', callback: () => newFolder(node) }
+    );
+  }
+
+  items.push(
+    { isDivider: true },
+    { icon: '✏️', title: 'Rename', callback: () => rename(node) },
+    { icon: '📋', title: 'Copy Path', callback: () => copyPath(node) },
+    { isDivider: true },
+    {
+      icon: '🗑️',
+      title: 'Delete',
+      isDisabled: node.data.isSystem,
+      callback: () => deleteItem(node)
+    }
+  );
+
+  return items;
+}
+
+User management menu:
+function createMenu(node, closeMenuCallback) {
+  const user = node.data;
+  return [
+    { icon: '👤', title: 'View Profile', callback: () => viewProfile(user) },
+    { icon: '✉️', title: 'Send Email', callback: () => sendEmail(user) },
+    { isDivider: true },
+    {
+      icon: '🔒',
+      title: user.isActive ? 'Deactivate' : 'Activate',
+      callback: () => toggleActive(user)
+    },
+    {
+      icon: '🗑️',
+      title: 'Remove',
+      isDisabled: user.isAdmin,
+      callback: () => removeUser(user)
+    }
+  ];
+}
+
+STYLING CONTEXT MENU
+--------------------
+Override default styles:
+
+.ltree-context-menu {
+  background: #1a1a1a;
+  border: 1px solid #333;
+  border-radius: 8px;
+  padding: 4px;
+}
+
+.ltree-context-menu-item {
+  padding: 8px 12px;
+  border-radius: 4px;
+}
+
+.ltree-context-menu-item:hover {
+  background: #2a2a2a;
+}
+
+.ltree-context-menu-item-disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+BEST PRACTICES
+--------------
+✅ Use callback-based approach for complex menus
+✅ Show icons for quick recognition
+✅ Use dividers to group related actions
+✅ Disable dangerous actions when not safe
+✅ Close menu after successful action
+✅ Handle async operations gracefully
+
+❌ Don't create menus with too many items (>10)
+❌ Don't forget to close menu after action
+❌ Don't use blocking operations in callbacks
+❌ Don't make all items look the same (use icons)