@keenmate/svelte-treeview 4.8.0 → 5.0.0-rc02

package/ai/typescript-types.txt

@@ -0,0 +1,357 @@
+TYPESCRIPT TYPES
+================
+
+CRITICAL: Full TypeScript support
+- Generic types for your data
+- All props and methods typed
+- Type exports from package
+
+BASIC TYPED USAGE
+-----------------
+<script lang="ts">
+  import { Tree } from '@keenmate/svelte-treeview';
+  import type { LTreeNode } from '@keenmate/svelte-treeview';
+
+  interface MyItem {
+    id: string;
+    path: string;
+    name: string;
+    type: 'file' | 'folder';
+  }
+
+  let data: MyItem[] = $state([]);
+  let selectedNode: LTreeNode<MyItem> | null = $state(null);
+</script>
+
+<Tree
+  {data}
+  idMember="id"
+  pathMember="path"
+  bind:selectedNode
+/>
+
+TYPE EXPORTS
+------------
+import type {
+  // Core types
+  LTreeNode,           // Tree node interface
+  Ltree,               // Tree instance interface
+  DropPosition,        // 'before' | 'after' | 'child'
+
+  // Context menu
+  ContextMenuItem,     // Menu item interface
+
+  // Results
+  InsertArrayResult,   // Insert operation result
+
+  // Internal (advanced)
+  NodeCallbacks,       // Event callback types
+  NodeConfig           // Node configuration
+} from '@keenmate/svelte-treeview';
+
+LTREENODE INTERFACE
+-------------------
+interface LTreeNode<T> {
+  // Path information
+  path: string;              // Full path "1.2.3"
+  pathSegment: string;       // Last segment "3"
+  parentPath: string | null; // Parent "1.2" or null
+
+  // Structure
+  level: number | null;      // Depth (0 = root)
+  children: Record<string, LTreeNode<T>>;
+  hasChildren: boolean;
+
+  // Your data
+  data: T | null;            // Original data object
+
+  // State
+  isExpanded: boolean;
+  isSelected: boolean;
+
+  // Drag and drop
+  isDraggable: boolean;
+  isDropAllowed: boolean;
+  allowedDropPositions: DropPosition[] | null | undefined;
+}
+
+DROPPOSITION TYPE
+-----------------
+type DropPosition = 'before' | 'after' | 'child';
+
+Usage:
+import type { DropPosition } from '@keenmate/svelte-treeview';
+
+function getAllowedPositions(node: LTreeNode<MyItem>): DropPosition[] | null {
+  if (node.data?.type === 'file') {
+    return ['before', 'after'];
+  }
+  return null;  // all positions
+}
+
+CONTEXTMENUITEM INTERFACE
+-------------------------
+interface ContextMenuItem {
+  icon?: string;
+  title: string;
+  isDisabled?: boolean;
+  callback: () => void | Promise<void>;
+  isDivider?: boolean;
+  className?: string;
+}
+
+Usage:
+function createMenu(node: LTreeNode<MyItem>, closeMenu: () => void): ContextMenuItem[] {
+  return [
+    {
+      icon: '📂',
+      title: 'Open',
+      callback: () => openItem(node.data)
+    },
+    { isDivider: true },
+    {
+      icon: '🗑️',
+      title: 'Delete',
+      isDisabled: node.data?.isProtected,
+      callback: () => deleteItem(node.data)
+    }
+  ];
+}
+
+INSERTARRAYRESULT INTERFACE
+---------------------------
+interface InsertArrayResult<T> {
+  successful: number;
+  failed: Array<{
+    node: LTreeNode<T>;
+    originalData: T;
+    error: string;
+  }>;
+  total: number;
+}
+
+Usage:
+let insertResult: InsertArrayResult<MyItem> | undefined = $state();
+
+$effect(() => {
+  if (insertResult) {
+    console.log(`${insertResult.successful} succeeded`);
+    console.log(`${insertResult.failed.length} failed`);
+  }
+});
+
+LTREE INTERFACE
+---------------
+interface Ltree<T> {
+  // Properties
+  root: LTreeNode<T>;
+  pathSeparator: string;
+  flatTreeNodes: LTreeNode<T>[];
+  nodeCount: number;
+  maxLevel: number;
+  filteredNodeCount: number;
+
+  // Methods
+  insertArray(data: T[]): InsertArrayResult<T>;
+  getNodeByPath(path: string): LTreeNode<T> | null;
+  expandNodes(path: string): Ltree<T>;
+  collapseNodes(path: string): Ltree<T>;
+  expandAll(path?: string): void;
+  collapseAll(path?: string): void;
+  filterNodes(searchText: string): void;
+  searchNodes(searchText: string): LTreeNode<T>[];
+
+  // Callbacks
+  getNodeAllowedDropPositions(node: LTreeNode<T>): DropPosition[] | null;
+}
+
+CALLBACK TYPES
+--------------
+// Node click
+onNodeClicked?: (node: LTreeNode<T>) => void;
+
+// Drag events
+onNodeDragStart?: (node: LTreeNode<T>, event: DragEvent) => void;
+onNodeDragOver?: (node: LTreeNode<T>, event: DragEvent) => void;
+onNodeDrop?: (
+  dropNode: LTreeNode<T> | null,
+  draggedNode: LTreeNode<T>,
+  position: DropPosition,
+  event: DragEvent,
+  operation: 'move' | 'copy'
+) => void;
+
+// Validation
+beforeDropCallback?: (
+  dropNode: LTreeNode<T> | null,
+  draggedNode: LTreeNode<T>,
+  position: DropPosition,
+  event: DragEvent,
+  operation: 'move' | 'copy'
+) => boolean | { position?: DropPosition; operation?: 'move' | 'copy' } | Promise<...>;
+
+// Value getters
+getDisplayValueCallback?: (node: LTreeNode<T>) => string;
+getSearchValueCallback?: (node: LTreeNode<T>) => string;
+getAllowedDropPositionsCallback?: (node: LTreeNode<T>) => DropPosition[] | null;
+
+// Context menu
+contextMenuCallback?: (
+  node: LTreeNode<T>,
+  closeMenu: () => void
+) => ContextMenuItem[];
+
+// Sort
+sortCallback?: (nodes: LTreeNode<T>[]) => LTreeNode<T>[];
+
+GENERIC TREE REFERENCE
+----------------------
+<script lang="ts">
+  import { Tree } from '@keenmate/svelte-treeview';
+
+  interface MyItem {
+    id: string;
+    path: string;
+    name: string;
+  }
+
+  let treeRef: Tree<MyItem>;
+</script>
+
+<Tree bind:this={treeRef} {data} ... />
+
+<button onclick={() => {
+  // Fully typed methods
+  const node = treeRef.getNodeByPath('1.2');
+  if (node) {
+    console.log(node.data?.name);  // string | undefined
+  }
+}}>
+  Get Node
+</button>
+
+STATISTICS TYPE
+---------------
+interface Statistics {
+  nodeCount: number;
+  maxLevel: number;
+  filteredNodeCount: number;
+  isIndexing: boolean;
+  pendingIndexCount: number;
+}
+
+const stats: Statistics = treeRef.statistics;
+
+COMPLEX DATA TYPES
+------------------
+// Union types
+interface FileItem {
+  id: string;
+  path: string;
+  name: string;
+  type: 'file';
+  size: number;
+  extension: string;
+}
+
+interface FolderItem {
+  id: string;
+  path: string;
+  name: string;
+  type: 'folder';
+  childCount: number;
+}
+
+type TreeItem = FileItem | FolderItem;
+
+// Type guards
+function isFile(item: TreeItem): item is FileItem {
+  return item.type === 'file';
+}
+
+function isFolder(item: TreeItem): item is FolderItem {
+  return item.type === 'folder';
+}
+
+// Usage in callbacks
+<Tree
+  data={items as TreeItem[]}
+  getDisplayValueCallback={(node) => {
+    if (!node.data) return '';
+    if (isFile(node.data)) {
+      return `${node.data.name} (${node.data.size}KB)`;
+    }
+    return `${node.data.name} (${node.data.childCount} items)`;
+  }}
+/>
+
+STRICT NULL CHECKS
+------------------
+Handle nullable data:
+
+onNodeClicked={(node) => {
+  // node.data can be null
+  if (node.data) {
+    console.log(node.data.name);
+  }
+}}
+
+// Or with optional chaining
+onNodeClicked={(node) => {
+  console.log(node.data?.name ?? 'Unknown');
+}}
+
+TYPE NARROWING IN TEMPLATES
+---------------------------
+<Tree {data}>
+  {#snippet nodeTemplate(node)}
+    {#if node.data}
+      <span>{node.data.name}</span>
+      {#if isFolder(node.data)}
+        <span class="count">({node.data.childCount})</span>
+      {/if}
+    {/if}
+  {/snippet}
+</Tree>
+
+EXTENDING TYPES
+---------------
+// Extend base node data
+interface BaseItem {
+  id: string;
+  path: string;
+  name: string;
+}
+
+interface ExtendedItem extends BaseItem {
+  createdAt: Date;
+  updatedAt: Date;
+  metadata: Record<string, unknown>;
+}
+
+// Use extended type
+let data: ExtendedItem[] = $state.raw([]);
+
+<Tree
+  {data}
+  idMember="id"
+  pathMember="path"
+  getDisplayValueCallback={(node) => {
+    const item = node.data;
+    if (!item) return '';
+    return `${item.name} (${item.createdAt.toLocaleDateString()})`;
+  }}
+/>
+
+BEST PRACTICES
+--------------
+✅ Define interface for your data type
+✅ Use type imports (import type { ... })
+✅ Handle null/undefined in callbacks
+✅ Use type guards for union types
+✅ Type tree reference with generic
+
+❌ Don't use `any` type
+❌ Don't ignore null checks on node.data
+❌ Don't cast without type guards
+❌ Don't forget generic parameter on Tree ref

package/dist/components/Node.svelte

@@ -4,14 +4,14 @@
 	import {getContext, onDestroy, type Snippet} from "svelte"
 	import type {Ltree, DropPosition, DropOperation} from "../ltree/types.js"
 	import type {RenderCoordinator} from "./RenderCoordinator.svelte.js"
-	import type {NodeCallbacks, NodeConfig} from "./Tree.svelte"
+	import type {NodeCallbacks, NodeConfig} from "../core/TreeController.svelte.js"
 	import { uiLogger } from "../logger.js"
 
 	// Define component props interface
 	// Callbacks and config come from context, drag state comes as props
 	interface Props {
 		node: LTreeNode<T>;
-		children?: Snippet<[T]>; // Keep the general children slot for backward compatibility
+		children?: Snippet<[LTreeNode<T>]>; // Keep the general children slot for backward compatibility
 
 		// Progressive rendering
 		progressiveRender?: boolean;
@@ -54,17 +54,24 @@
 	const callbacks = getContext<NodeCallbacks<T>>('NodeCallbacks');
 	const config = getContext<NodeConfig>('NodeConfig');
 
-	// Use $derived so values track mutations on the shared config proxy
-	const shouldToggleOnNodeClick = $derived(config.shouldToggleOnNodeClick);
-	const expandIconClass = $derived(config.expandIconClass);
-	const collapseIconClass = $derived(config.collapseIconClass);
-	const leafIconClass = $derived(config.leafIconClass);
-	const selectedNodeClass = $derived(config.selectedNodeClass);
-	const dragOverNodeClass = $derived(config.dragOverNodeClass);
-	const dragDropMode = $derived(config.dragDropMode);
+	// Destructure config for convenience.
+	// Works reactively because nodeConfig uses $state() (not .raw()) and is mutated
+	// in-place via Object.assign, so the proxy reference stays the same.
+	const {
+		shouldToggleOnNodeClick,
+		expandIconClass,
+		collapseIconClass,
+		leafIconClass,
+		selectedNodeClass,
+		dragOverNodeClass,
+		allowCopy,
+	} = config;
+
+	// Read dropZoneMode and dropZoneStart through the proxy each time (not
+	// destructured) so they stay reactive in flat mode where nodes are NOT
+	// recreated on config change.
 	const dropZoneMode = $derived(config.dropZoneMode);
 	const dropZoneStart = $derived(config.dropZoneStart);
-	const allowCopy = $derived(config.allowCopy);
 
 	// Compute if THIS node is the one being hovered for drop
 	const isHoveredForDrop = $derived(hoveredNodeForDropPath === node.path);
@@ -72,16 +79,11 @@
 	const tree = getContext<Ltree<T>>("Ltree")
 	const renderCoordinator = getContext<RenderCoordinator | null>("RenderCoordinator")
 
-	// Per-node reactive signal — each NodeSignal has its own $state, so
-	// bumping one signal only re-renders THIS Node, not all siblings.
-	const nodeSignal = tree.getNodeSignal(String(node.id));
-	const nodeRev = $derived(nodeSignal?.value ?? 0);
-
 	// Drag over state
 	let isDraggedOver = $state(false);
 
 	// Track glow position for glow mode
-	let glowPosition = $state<'above' | 'below' | 'child' | null>(null);
+	let glowPosition = $state<'before' | 'after' | 'child' | null>(null);
 
 	// Get allowed drop positions for this node (empty/undefined = all allowed)
 	// Uses tree.getNodeAllowedDropPositions which checks callback > member > node property
@@ -97,28 +99,32 @@
 
 	// Calculate glow position based on mouse position in the node row
 	// Respects allowedDropPositions - snaps to nearest allowed position
-	function calculateGlowPosition(event: DragEvent, element: HTMLElement): 'above' | 'below' | 'child' | null {
+	// Uses dropZoneStart to determine the child zone threshold
+	function calculateGlowPosition(event: DragEvent, element: HTMLElement): 'before' | 'after' | 'child' | null {
 		const rect = element.getBoundingClientRect();
 		const x = event.clientX - rect.left;
 		const y = event.clientY - rect.top;
 		const width = rect.width;
 		const height = rect.height;
 
-		// Calculate the ideal position based on mouse position
-		let idealPosition: DropPosition;
 		// Convert dropZoneStart to pixels: number = percentage, string = as-is (px or %)
 		const startPx = typeof dropZoneStart === 'number'
 			? (dropZoneStart / 100) * width
-			: dropZoneStart.endsWith('px')
+			: typeof dropZoneStart === 'string' && dropZoneStart.endsWith('px')
 				? parseFloat(dropZoneStart)
-				: (parseFloat(dropZoneStart) / 100) * width;
+				: typeof dropZoneStart === 'string'
+					? (parseFloat(dropZoneStart) / 100) * width
+					: width / 2;
+		const childThreshold = isNaN(startPx) ? width / 2 : startPx;
 
-		if (x > startPx) {
+		// Calculate the ideal position based on mouse position
+		let idealPosition: DropPosition;
+		if (x > childThreshold) {
 			idealPosition = 'child';
 		} else if (y < height / 2) {
-			idealPosition = 'above';
+			idealPosition = 'before';
 		} else {
-			idealPosition = 'below';
+			idealPosition = 'after';
 		}
 
 		// If no restrictions, return the ideal position
@@ -138,17 +144,20 @@
 		}
 
 		// Multiple positions allowed but not the ideal one
-		// For above/below: pick based on Y position
+		// For before/after: pick based on Y position
 		// For child: pick based on what's available
-		if (allowedPositions.includes('above') && allowedPositions.includes('below')) {
-			// Both above and below allowed, pick based on Y
-			return y < height / 2 ? 'above' : 'below';
+		if (allowedPositions.includes('before') && allowedPositions.includes('after')) {
+			// Both before and after allowed, pick based on Y
+			return y < height / 2 ? 'before' : 'after';
 		}
 
 		// Return the first allowed position
 		return allowedPositions[0];
 	}
 
+	// Resolve isCollapsible via tree's resolution method (callback > member > node property)
+	const isCollapsible = $derived(tree.getNodeIsCollapsible(node));
+
 	// Convert reactive statements to derived values
 	// In flat mode, children rendering is handled by Tree.svelte, so we skip these computations
 	const childrenArray = $derived(!flatMode ? Object.values(node?.children || []) : [])
@@ -242,12 +251,11 @@
 	});
 
 	function toggleExpanded() {
-		if (node.hasChildren) {
+		if (node.hasChildren && isCollapsible) {
 			const newState = !node.isExpanded
 			uiLogger.debug(`${newState ? 'Expanding' : 'Collapsing'} node: ${node.path}`)
 			node.isExpanded = newState
-			tree.bumpNodeRev(node) // re-render expand/collapse icon via {#key nodeRev}
-			tree.refresh() // structural: recompute visibleFlatNodes
+			tree.refresh()
 		}
 	}
 
@@ -260,7 +268,6 @@
 	}
 </script>
 
-{#key nodeRev}
 <!-- svelte-ignore a11y_no_static_element_interactions -->
 <div
 	class="ltree-node"
@@ -271,7 +278,7 @@
 	<div class="ltree-node-row">
 		<!-- Toggle icon with its own click handler -->
 		<!-- svelte-ignore a11y_click_events_have_key_events -->
-		{#if hasChildren}
+		{#if hasChildren && isCollapsible}
 			<span
 				class="ltree-toggle-icon ltree-clickable {node.isExpanded
 					? collapseIconClass
@@ -290,12 +297,12 @@
 			class="ltree-node-content {node.isSelected ? selectedNodeClass : ''} {isDraggedOver && dragOverNodeClass ? dragOverNodeClass : ''}"
 			class:ltree-clickable={node.isSelectable}
 			class:ltree-dragged={isDraggedNode}
-			class:ltree-draggable={node?.isDraggable && dragDropMode !== 'none'}
-			class:ltree-glow-above={dropZoneMode === 'glow' && isDragInProgress && isHoveredForDrop && glowPosition === 'above' && isPositionAllowed('above')}
-			class:ltree-glow-below={dropZoneMode === 'glow' && isDragInProgress && isHoveredForDrop && glowPosition === 'below' && isPositionAllowed('below')}
+			class:ltree-draggable={node?.isDraggable}
+			class:ltree-glow-before={dropZoneMode === 'glow' && isDragInProgress && isHoveredForDrop && glowPosition === 'before' && isPositionAllowed('before')}
+			class:ltree-glow-after={dropZoneMode === 'glow' && isDragInProgress && isHoveredForDrop && glowPosition === 'after' && isPositionAllowed('after')}
 			class:ltree-glow-child={dropZoneMode === 'glow' && isDragInProgress && isHoveredForDrop && glowPosition === 'child' && isPositionAllowed('child')}
 			class:ltree-drop-copy={isDragInProgress && isHoveredForDrop && dropOperation === 'copy'}
-			draggable={node?.isDraggable && dragDropMode !== 'none'}
+			draggable={node?.isDraggable}
 			onclick={(e) => {
 				e.stopPropagation();
 				_onNodeClicked();
@@ -305,7 +312,7 @@
 				callbacks.onNodeRightClicked(node, e);
 			}}
 			ondragstart={(e) => {
-				if (node?.isDraggable && dragDropMode !== 'none' && e.dataTransfer) {
+				if (node?.isDraggable && e.dataTransfer) {
 					e.dataTransfer.effectAllowed = allowCopy ? "copyMove" : "move";
 					e.dataTransfer.setData(
 						"application/svelte-treeview",
@@ -365,6 +372,7 @@
 				{tree.getNodeDisplayValue(node)}
 			{/if}
 		</div>
+
 	</div>
 
 	<!-- In flat mode, children are rendered by Tree.svelte, not recursively here -->
@@ -391,4 +399,3 @@
 		</div>
 	{/if}
 </div>
-{/key}

package/dist/components/Node.svelte.d.ts

@@ -5,7 +5,7 @@ import type { DropPosition, DropOperation } from "../ltree/types.js";
 declare function $$render<T>(): {
     props: {
         node: LTreeNode<T>;
-        children?: Snippet<[T]>;
+        children?: Snippet<[LTreeNode<T>]>;
         progressiveRender?: boolean;
         renderBatchSize?: number;
         isDraggedNode?: boolean;