@keenmate/svelte-treeview 5.0.0-rc08 → 5.0.0-rc09

package/component-variables.manifest.json

@@ -0,0 +1,142 @@
+{
+	"$schema": "https://raw.githubusercontent.com/keenmate/schemas/main/component-variables.schema.json",
+	"component": "@keenmate/svelte-treeview",
+	"prefix": "ltree",
+	"baseVariables": [
+		{ "name": "base-accent-color", "required": true, "usage": "Primary accent — selection, drop-zones, focus rings, debug panel. Tints derived via color-mix()." },
+		{ "name": "base-success-color", "required": false, "usage": "Drop-valid border and dragover highlight" },
+		{ "name": "base-danger-color", "required": false, "usage": "Drop-invalid border, danger context-menu items, scroll-highlight arrows" },
+		{ "name": "base-main-bg", "required": false, "usage": "Used for --ltree-light (context-menu hover tint, debug stat chips)" },
+		{ "name": "base-border-color", "required": true, "usage": "Default border color (checkbox, context-menu, spinner track)" },
+		{ "name": "base-hover-bg", "required": false, "usage": "Node row hover background" },
+		{ "name": "base-text-color-1", "required": true, "usage": "Primary body text color (node labels, context-menu items)" },
+		{ "name": "base-text-color-3", "required": false, "usage": "Muted text (path, toggle icon, loading 'more', node-path)" },
+		{ "name": "base-text-color-4", "required": false, "usage": "Subtle text (context-menu shortcut, submenu arrow, divider label)" },
+		{ "name": "base-text-color-on-accent", "required": false, "usage": "Text on accent backgrounds — checkbox checkmark color" },
+		{ "name": "base-input-bg", "required": false, "usage": "Checkbox background (unchecked)" },
+		{ "name": "base-dropdown-bg", "required": false, "usage": "Context-menu and submenu background" },
+		{ "name": "base-dropdown-box-shadow", "required": false, "usage": "Context-menu shadow" },
+		{ "name": "base-font-family", "required": false, "usage": "All text in component" },
+		{ "name": "base-font-size-xs", "required": false, "usage": "Small text — node path, context-menu shortcut, icon font-size (multiplier × --ltree-rem)" },
+		{ "name": "base-font-size-sm", "required": false, "usage": "Default node text and context-menu items (multiplier × --ltree-rem)" },
+		{ "name": "base-font-weight-medium", "required": false, "usage": "Node label weight" },
+		{ "name": "base-border-radius-sm", "required": false, "usage": "Checkbox, context-menu, node-content border radius (multiplier × --ltree-rem)" }
+	],
+	"componentVariables": [
+		{ "name": "ltree-rem", "category": "sizing", "usage": "Base sizing unit for proportional scaling (default 10px). Set to 1rem to scale with document font-size." },
+
+		{ "name": "ltree-primary", "category": "color", "usage": "Primary accent color (selection, focus, links). Tints derived via color-mix()." },
+		{ "name": "ltree-success", "category": "color", "usage": "Success color (drop-valid border, dragover-highlight)" },
+		{ "name": "ltree-danger", "category": "color", "usage": "Danger color (drop-invalid, scroll-highlight arrows, danger menu items)" },
+		{ "name": "ltree-light", "category": "color", "usage": "Light surface (context-menu hover, debug stat chips)" },
+		{ "name": "ltree-border", "category": "color", "usage": "Default border color" },
+		{ "name": "ltree-body-color", "category": "color", "usage": "Default body text color" },
+
+		{ "name": "ltree-font-family", "category": "typography", "usage": "Font family for all tree text" },
+		{ "name": "ltree-node-font-size", "category": "typography", "usage": "Node row text size" },
+		{ "name": "ltree-node-icon-font-size", "category": "typography", "usage": "Per-node icon font size (emoji, etc.)" },
+		{ "name": "ltree-node-icon-margin-right", "category": "spacing", "usage": "Gap between node icon and label" },
+		{ "name": "ltree-node-label-font-weight", "category": "typography", "usage": "Node label weight" },
+		{ "name": "ltree-node-label-margin-right", "category": "spacing", "usage": "Gap after node label" },
+		{ "name": "ltree-node-path-font-size", "category": "typography", "usage": "Path / debug muted text size" },
+		{ "name": "ltree-node-path-color", "category": "color", "usage": "Path / debug muted text color" },
+
+		{ "name": "ltree-node-indent-per-level", "category": "spacing", "usage": "Indentation added per nesting level" },
+		{ "name": "ltree-node-content-padding", "category": "spacing", "usage": "Inner padding of a node row" },
+		{ "name": "ltree-node-content-border-radius", "category": "border", "usage": "Node row corner rounding" },
+		{ "name": "ltree-node-hover-bg", "category": "surface", "usage": "Node row hover background" },
+		{ "name": "ltree-children-margin-top", "category": "spacing", "usage": "Top margin of nested child list" },
+
+		{ "name": "ltree-toggle-icon-size", "category": "sizing", "usage": "Toggle icon (chevron / +/- / arrow / leaf) SVG size" },
+		{ "name": "ltree-toggle-icon-width", "category": "sizing", "usage": "Width reserved for the toggle column" },
+		{ "name": "ltree-toggle-icon-color", "category": "color", "usage": "Toggle icon color (via currentColor mask)" },
+		{ "name": "ltree-toggle-icon-margin-right", "category": "spacing", "usage": "Gap between toggle and node content" },
+		{ "name": "ltree-toggle-icon-transition", "category": "animation", "usage": "Rotation animation timing" },
+
+		{ "name": "ltree-checkbox-size", "category": "sizing", "usage": "Checkbox square dimension" },
+		{ "name": "ltree-checkbox-border-width", "category": "border", "usage": "Checkbox border thickness (hairline, does not scale)" },
+		{ "name": "ltree-checkbox-border-color", "category": "color", "usage": "Unchecked checkbox border" },
+		{ "name": "ltree-checkbox-border-radius", "category": "border", "usage": "Checkbox corner rounding" },
+		{ "name": "ltree-checkbox-bg", "category": "surface", "usage": "Unchecked checkbox background" },
+		{ "name": "ltree-checkbox-checked-bg", "category": "surface", "usage": "Checked / indeterminate checkbox background" },
+		{ "name": "ltree-checkbox-checked-border-color", "category": "color", "usage": "Checked checkbox border" },
+		{ "name": "ltree-checkbox-checkmark-color", "category": "color", "usage": "Tick / dash glyph color" },
+		{ "name": "ltree-checkbox-focus-ring-width", "category": "border", "usage": "Focus-visible ring thickness" },
+		{ "name": "ltree-checkbox-focus-ring-color", "category": "color", "usage": "Focus-visible ring color (defaults to a 25% tint of --ltree-primary)" },
+		{ "name": "ltree-checkbox-focus-ring", "category": "border", "usage": "Composed focus-visible box-shadow (uses the two parts above; override directly for full control)" },
+
+		{ "name": "ltree-highlight-bg", "category": "state", "usage": "Explorer-style highlighted node background" },
+		{ "name": "ltree-highlight-color", "category": "state", "usage": "Highlighted node text color" },
+		{ "name": "ltree-multi-selected-bg", "category": "state", "usage": "Multi-select tint background" },
+		{ "name": "ltree-multi-selected-outline", "category": "state", "usage": "Multi-select outline" },
+
+		{ "name": "ltree-dragover-bg", "category": "state", "usage": "Drag-over background tint" },
+		{ "name": "ltree-dragover-shadow", "category": "state", "usage": "Drag-over glow shadow" },
+		{ "name": "ltree-drop-placeholder-bg", "category": "state", "usage": "Empty-tree drop placeholder background" },
+		{ "name": "ltree-drop-placeholder-color", "category": "state", "usage": "Placeholder text color" },
+		{ "name": "ltree-drop-placeholder-border-radius", "category": "border", "usage": "Placeholder corner rounding" },
+		{ "name": "ltree-drop-placeholder-min-height", "category": "sizing", "usage": "Placeholder min height" },
+
+		{ "name": "ltree-drop-zone-border-radius", "category": "border", "usage": "Drop zone corner rounding" },
+		{ "name": "ltree-drop-zone-before-bg", "category": "drop-zone", "usage": "Before zone resting background (sage)" },
+		{ "name": "ltree-drop-zone-before-color", "category": "drop-zone", "usage": "Before zone resting text" },
+		{ "name": "ltree-drop-zone-before-active-bg", "category": "drop-zone", "usage": "Before zone active background" },
+		{ "name": "ltree-drop-zone-before-active-color", "category": "drop-zone", "usage": "Before zone active text" },
+		{ "name": "ltree-drop-zone-before-active-shadow", "category": "drop-zone", "usage": "Before zone active shadow" },
+		{ "name": "ltree-drop-zone-after-bg", "category": "drop-zone", "usage": "After zone resting background (coral)" },
+		{ "name": "ltree-drop-zone-after-color", "category": "drop-zone", "usage": "After zone resting text" },
+		{ "name": "ltree-drop-zone-after-active-bg", "category": "drop-zone", "usage": "After zone active background" },
+		{ "name": "ltree-drop-zone-after-active-color", "category": "drop-zone", "usage": "After zone active text" },
+		{ "name": "ltree-drop-zone-after-active-shadow", "category": "drop-zone", "usage": "After zone active shadow" },
+		{ "name": "ltree-drop-zone-child-bg", "category": "drop-zone", "usage": "Child zone resting background (lavender)" },
+		{ "name": "ltree-drop-zone-child-color", "category": "drop-zone", "usage": "Child zone resting text" },
+		{ "name": "ltree-drop-zone-child-active-bg", "category": "drop-zone", "usage": "Child zone active background" },
+		{ "name": "ltree-drop-zone-child-active-color", "category": "drop-zone", "usage": "Child zone active text" },
+		{ "name": "ltree-drop-zone-child-active-shadow", "category": "drop-zone", "usage": "Child zone active shadow" },
+
+		{ "name": "ltree-drop-glow-before-color", "category": "drop-zone", "usage": "Border glow color for 'before' position" },
+		{ "name": "ltree-drop-glow-after-color", "category": "drop-zone", "usage": "Border glow color for 'after' position" },
+		{ "name": "ltree-drop-glow-child-color", "category": "drop-zone", "usage": "Border glow color for 'child' position" },
+		{ "name": "ltree-drop-glow-child-bg", "category": "drop-zone", "usage": "Child zone glow background tint" },
+		{ "name": "ltree-drop-glow-size", "category": "border", "usage": "Glow border thickness (hairline, does not scale)" },
+		{ "name": "ltree-drop-arrow-size", "category": "sizing", "usage": "Direction arrow size in glow mode" },
+		{ "name": "ltree-drop-arrow-position", "category": "spacing", "usage": "Horizontal arrow position (% of node width)" },
+		{ "name": "ltree-drop-arrow-before-rotation", "category": "animation", "usage": "Arrow rotation for 'before' position" },
+		{ "name": "ltree-drop-arrow-after-rotation", "category": "animation", "usage": "Arrow rotation for 'after' position" },
+		{ "name": "ltree-drop-arrow-child-rotation", "category": "animation", "usage": "Arrow rotation for 'child' position (45deg by default)" },
+		{ "name": "ltree-drop-arrow-before-image", "category": "icon", "usage": "SVG data URL for the 'before' direction arrow" },
+		{ "name": "ltree-drop-arrow-after-image", "category": "icon", "usage": "SVG data URL for the 'after' direction arrow" },
+		{ "name": "ltree-drop-arrow-child-image", "category": "icon", "usage": "SVG data URL for the 'child' direction arrow" },
+
+		{ "name": "tree-ghost-bg", "category": "state", "usage": "Touch drag ghost background (legacy prefix, kept for backward compat)" },
+		{ "name": "tree-ghost-color", "category": "state", "usage": "Touch drag ghost text color (legacy prefix)" },
+
+		{ "name": "ltree-context-menu-bg", "category": "context-menu", "usage": "Menu background" },
+		{ "name": "ltree-context-menu-border-color", "category": "context-menu", "usage": "Menu border color" },
+		{ "name": "ltree-context-menu-border-radius", "category": "border", "usage": "Menu corner rounding" },
+		{ "name": "ltree-context-menu-shadow", "category": "context-menu", "usage": "Menu drop shadow" },
+		{ "name": "ltree-context-menu-min-width", "category": "sizing", "usage": "Menu minimum width" },
+		{ "name": "ltree-context-menu-padding", "category": "spacing", "usage": "Menu inner padding" },
+		{ "name": "ltree-context-menu-item-padding", "category": "spacing", "usage": "Menu item padding" },
+		{ "name": "ltree-context-menu-item-font-size", "category": "typography", "usage": "Menu item font size" },
+		{ "name": "ltree-context-menu-item-color", "category": "color", "usage": "Menu item text color" },
+		{ "name": "ltree-context-menu-item-hover-bg", "category": "surface", "usage": "Menu item hover background" },
+		{ "name": "ltree-context-menu-icon-size", "category": "sizing", "usage": "Menu icon column width" },
+		{ "name": "ltree-context-menu-icon-font-size", "category": "typography", "usage": "Menu icon font size" },
+		{ "name": "ltree-context-menu-shortcut-color", "category": "color", "usage": "Keyboard shortcut hint color" },
+		{ "name": "ltree-context-menu-shortcut-font-size", "category": "typography", "usage": "Keyboard shortcut hint font size" },
+		{ "name": "ltree-context-menu-arrow-color", "category": "color", "usage": "Submenu arrow color" },
+		{ "name": "ltree-context-menu-divider-color", "category": "color", "usage": "Divider line color" },
+		{ "name": "ltree-context-menu-divider-label-color", "category": "color", "usage": "Named divider label color" },
+
+		{ "name": "ltree-loading-bg", "category": "surface", "usage": "Loading overlay background" },
+		{ "name": "ltree-loading-color", "category": "color", "usage": "'Loading more…' text color" },
+		{ "name": "ltree-spinner-size", "category": "sizing", "usage": "Spinner diameter" },
+		{ "name": "ltree-spinner-track", "category": "color", "usage": "Spinner background ring color" },
+		{ "name": "ltree-spinner-color", "category": "color", "usage": "Spinner active color" },
+
+		{ "name": "ltree-scroll-highlight-bg", "category": "state", "usage": "scrollToPath highlight background flash" },
+		{ "name": "ltree-scroll-highlight-shadow", "category": "state", "usage": "scrollToPath highlight glow" },
+		{ "name": "ltree-scroll-highlight-arrow-color", "category": "state", "usage": "scrollToPath direction arrow color" }
+	]
+}

package/dist/components/Node.svelte

@@ -54,21 +54,21 @@
 	const callbacks = getContext<NodeCallbacks<T>>('NodeCallbacks');
 	const config = getContext<NodeConfig>('NodeConfig');
 
-	// 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 {
-		expandIconClass,
-		collapseIconClass,
-		leafIconClass,
-		highlightedNodeClass,
-		focusedNodeClass,
-		dragOverNodeClass,
-		allowCopy,
-	} = config;
+	// Read every config field through $derived so updates from controller.update()
+	// or the controller's runtime $effect syncs propagate into this Node's render.
+	// Plain destructuring would snapshot primitives once and never react.
+	const expandIconClass = $derived(config.expandIconClass);
+	const collapseIconClass = $derived(config.collapseIconClass);
+	const leafIconClass = $derived(config.leafIconClass);
+	const highlightedNodeClass = $derived(config.highlightedNodeClass);
+	const focusedNodeClass = $derived(config.focusedNodeClass);
+	// dragOverNodeClass is applied to the DOM directly by the controller
+	// (see hoveredNodeForDrop $effect in TreeController) — no per-Node binding.
+	const allowCopy = $derived(config.allowCopy);
 	const clickBehavior = $derived(config.clickBehavior);
 	const showCheckboxes = $derived(config.showCheckboxes);
 	const checkboxMode = $derived(config.checkboxMode);
+	const clickTogglesCheckbox = $derived(config.clickTogglesCheckbox);
 
 	// Indeterminate state: driven by controller's _updateAncestorVisualStates
 	const isIndeterminate = $derived(checkboxMode === 'cascade' && node.visualState === 'indeterminate');
@@ -81,15 +81,15 @@
 	const accordionExpand = $derived(config.accordionExpand);
 	const toggleIconMode = $derived(config.toggleIconMode);
 
-	// Compute if THIS node is the one being hovered for drop
+	// Compute if THIS node is the one being hovered for drop.
+	// Single source of truth from the controller — guarantees exactly one highlighted
+	// row at a time, unlike the per-node local flag we used before (HTML5 dragleave
+	// is unreliable and leaked stale highlights when moving fast between rows).
 	const isHoveredForDrop = $derived(hoveredNodeForDropPath === node.path);
 
 	const tree = getContext<Ltree<T>>("Ltree")
 	const renderCoordinator = getContext<RenderCoordinator | null>("RenderCoordinator")
 
-	// Drag over state
-	let isDraggedOver = $state(false);
-
 	// Track glow position for glow mode
 	let glowPosition = $state<'before' | 'after' | 'child' | null>(null);
 
@@ -177,8 +177,8 @@
 	// — only applied before first-child nodes (where level > previous node's level).
 	const indentStyle = $derived(
 		flatMode
-			? `margin-left: calc(${node?.level || 1} * var(--tree-node-indent-per-level, 0.5rem))${flatGap ? '; margin-top: 2px' : ''}`
-			: `margin-left: var(--tree-node-indent-per-level, 0.5rem)`,
+			? `margin-left: calc(${node?.level || 1} * var(--ltree-node-indent-per-level, 0.5rem))${flatGap ? '; margin-top: 2px' : ''}`
+			: `margin-left: var(--ltree-node-indent-per-level, 0.5rem)`,
 	)
 
 	// Progressive rendering state - only used in recursive mode
@@ -296,14 +296,27 @@
 	function _onNodeClicked(event?: MouseEvent) {
 		uiLogger.debug(`Node clicked: ${node.path}`, { id: node.id, hasChildren: node.hasChildren })
 		const modifiers = event ? { ctrl: event.ctrlKey || event.metaKey, shift: event.shiftKey } : undefined;
+		const hasModifiers = !!(modifiers?.ctrl || modifiers?.shift);
+
+		// Plain click on a selectable node with checkboxes shown → toggle the checkbox
+		// instead of focusing/highlighting. Expand still happens if clickBehavior asks for it.
+		// Modified clicks (Ctrl/Shift) fall through to the normal multi-highlight path.
+		if (clickTogglesCheckbox && showCheckboxes && node.isSelectable && !hasModifiers) {
+			callbacks.onCheckboxToggle(node, { skipFocus: true });
+			if (clickBehavior !== 'select') toggleExpanded();
+			return;
+		}
 
 		if (clickBehavior === 'expand') {
-			// Expand only — no selection callback
-			toggleExpanded()
+			// Expand only — no selection callback. Ctrl/Shift have no meaning here
+			// (no selection to extend), so they shouldn't toggle expand either.
+			if (!hasModifiers) toggleExpanded()
 		} else if (clickBehavior === 'expand-and-focus') {
-			// Select + expand on single click
+			// Select + expand on single click. Modified clicks are reserved for
+			// highlight management — don't also toggle expand (matches OS file
+			// explorers where Ctrl/Shift+click manages selection without opening).
 			callbacks.onNodeClicked(node, modifiers)
-			toggleExpanded()
+			if (!hasModifiers) toggleExpanded()
 		} else {
 			// 'select' — single click selects only
 			callbacks.onNodeClicked(node, modifiers)
@@ -365,7 +378,7 @@
 		<!-- svelte-ignore a11y_click_events_have_key_events -->
 		<!-- svelte-ignore a11y_no_static_element_interactions -->
 		<div
-			class="ltree-node-content {node.isHighlighted ? highlightedNodeClass : ''} {node.isFocused && focusedNodeClass ? focusedNodeClass : ''} {isDraggedOver && dragOverNodeClass ? dragOverNodeClass : ''}"
+			class="ltree-node-content {node.isHighlighted ? highlightedNodeClass : ''} {node.isFocused && focusedNodeClass ? focusedNodeClass : ''}"
 			class:ltree-clickable={node.isSelectable}
 			class:ltree-dragged={isDraggedNode}
 			class:ltree-draggable={node?.isDraggable}
@@ -403,7 +416,6 @@
 					if (e.dataTransfer) {
 						e.dataTransfer.dropEffect = (allowCopy && e.ctrlKey) ? 'copy' : 'move';
 					}
-					isDraggedOver = true;
 					// In glow mode, calculate and update the glow position
 					if (dropZoneMode === 'glow') {
 						glowPosition = calculateGlowPosition(e, e.currentTarget as HTMLElement);
@@ -417,7 +429,6 @@
 				const y = e.clientY;
 
 				if (x < rect.left || x >= rect.right || y < rect.top || y >= rect.bottom) {
-					isDraggedOver = false;
 					glowPosition = null;
 					callbacks.onNodeDragLeave(node, e);
 				}
@@ -428,7 +439,6 @@
 				if (e.dataTransfer) {
 					e.dataTransfer.dropEffect = (allowCopy && e.ctrlKey) ? 'copy' : 'move';
 				}
-				isDraggedOver = false;
 				// In glow mode, use the calculated glowPosition for the drop
 				if (dropZoneMode === 'glow' && glowPosition) {
 					callbacks.onZoneDrop(node, glowPosition, e);

package/dist/components/Tree.svelte

@@ -12,6 +12,7 @@
 		type DropOperation,
 		type ClickBehavior,
 		type CheckboxMode,
+		type SelectionMode,
 		type TreeChange,
 		type ApplyChangesResult
 	} from '../ltree/types.js';
@@ -31,8 +32,11 @@
 		parentPathMember?: string | null | undefined;
 		levelMember?: string | null | undefined;
 		isExpandedMember?: string | null | undefined;
+		getIsExpandedCallback?: (node: LTreeNode<T>) => boolean;
 		isSelectableMember?: string | null | undefined;
+		getIsSelectableCallback?: (node: LTreeNode<T>) => boolean;
 		isSelectedMember?: string | null | undefined;
+		getIsSelectedCallback?: (node: LTreeNode<T>) => boolean;
 		isDraggableMember?: string | null | undefined;
 		getIsDraggableCallback?: (node: LTreeNode<T>) => boolean;
 		isDropAllowedMember?: string | null | undefined;
@@ -76,8 +80,16 @@
 		// BEHAVIOUR
 		expandLevel?: number | null | undefined;
 		clickBehavior?: ClickBehavior | null | undefined;
+		/**
+		 * `'single'` (default): plain click highlights one node; Ctrl/Shift+click
+		 * degrade to plain click; Shift+Arrow / Enter are no-ops.
+		 * `'multi'`: Ctrl-toggle, Shift-range, Shift+Arrow extend, Enter toggles
+		 * highlight on the focused node.
+		 */
+		selectionMode?: SelectionMode | null | undefined;
 		showCheckboxes?: boolean | null | undefined;
 		checkboxMode?: CheckboxMode | null | undefined;
+		clickTogglesCheckbox?: boolean | null | undefined;
 		beforeCheckboxToggleCallback?: (node: LTreeNode<T>, checked: boolean, affectedPaths: string[]) => boolean | string[] | void;
 		rangeSelectionMode?: 'visual' | 'logical';
 		initializeIndexCallback?: () => Index;
@@ -185,8 +197,11 @@
 		hasChildrenMember,
 
 		isExpandedMember,
+		getIsExpandedCallback,
 		isSelectableMember,
+		getIsSelectableCallback,
 		isSelectedMember,
+		getIsSelectedCallback,
 		isDraggableMember,
 		getIsDraggableCallback,
 		isDropAllowedMember,
@@ -223,8 +238,10 @@
 		expandLevel = 2,
 
 		clickBehavior = 'expand-and-focus',
+		selectionMode = 'single',
 		showCheckboxes = false,
 		checkboxMode = 'independent',
+		clickTogglesCheckbox = false,
 		beforeCheckboxToggleCallback,
 		rangeSelectionMode = 'visual',
 		shouldUseInternalSearchIndex = true,
@@ -306,8 +323,11 @@
 		levelMember,
 		hasChildrenMember,
 		isExpandedMember,
+		getIsExpandedCallback,
 		isSelectableMember,
+		getIsSelectableCallback,
 		isSelectedMember,
+		getIsSelectedCallback,
 		isDraggableMember,
 		getIsDraggableCallback,
 		isDropAllowedMember,
@@ -330,8 +350,10 @@
 		selectedPaths,
 		expandLevel,
 		clickBehavior,
+		selectionMode,
 		showCheckboxes,
 		checkboxMode,
+		clickTogglesCheckbox,
 		beforeCheckboxToggleCallback,
 		rangeSelectionMode,
 		shouldUseInternalSearchIndex,
@@ -440,8 +462,10 @@
 
 	// Visual config sync (drives nodeConfig update via controller's internal effect)
 	$effect(() => { controller.clickBehavior = clickBehavior ?? 'expand-and-focus'; });
+	$effect(() => { controller.selectionMode = selectionMode ?? 'single'; });
 	$effect(() => { controller.showCheckboxes = showCheckboxes ?? false; });
 	$effect(() => { controller.checkboxMode = checkboxMode ?? 'independent'; });
+	$effect(() => { controller.clickTogglesCheckbox = clickTogglesCheckbox ?? false; });
 	$effect(() => { controller.beforeCheckboxToggleHandler = beforeCheckboxToggleCallback; });
 	$effect(() => { controller.rangeSelectionMode = rangeSelectionMode ?? 'visual'; });
 	$effect(() => { controller.expandIconClass = expandIconClass ?? 'ltree-icon-expand'; });
@@ -683,8 +707,11 @@
 				| "levelMember"
 				| "hasChildrenMember"
 				| "isExpandedMember"
+				| "getIsExpandedCallback"
 				| "isSelectableMember"
+				| "getIsSelectableCallback"
 				| "isSelectedMember"
+				| "getIsSelectedCallback"
 				| "isDraggableMember"
 				| "getIsDraggableCallback"
 				| "isDropAllowedMember"
@@ -703,8 +730,10 @@
 				| "selectedPaths"
 				| "expandLevel"
 				| "clickBehavior"
+				| "selectionMode"
 				| "showCheckboxes"
 				| "checkboxMode"
+				| "clickTogglesCheckbox"
 				| "beforeCheckboxToggleCallback"
 				| "rangeSelectionMode"
 				| "shouldUseInternalSearchIndex"
@@ -756,8 +785,11 @@
 		if (updates.levelMember !== undefined) levelMember = updates.levelMember;
 		if (updates.hasChildrenMember !== undefined) hasChildrenMember = updates.hasChildrenMember;
 		if (updates.isExpandedMember !== undefined) isExpandedMember = updates.isExpandedMember;
+		if (updates.getIsExpandedCallback !== undefined) getIsExpandedCallback = updates.getIsExpandedCallback;
 		if (updates.isSelectableMember !== undefined) isSelectableMember = updates.isSelectableMember;
+		if (updates.getIsSelectableCallback !== undefined) getIsSelectableCallback = updates.getIsSelectableCallback;
 		if (updates.isSelectedMember !== undefined) isSelectedMember = updates.isSelectedMember;
+		if (updates.getIsSelectedCallback !== undefined) getIsSelectedCallback = updates.getIsSelectedCallback;
 		if (updates.isDraggableMember !== undefined) isDraggableMember = updates.isDraggableMember;
 		if (updates.getIsDraggableCallback !== undefined) getIsDraggableCallback = updates.getIsDraggableCallback;
 		if (updates.isDropAllowedMember !== undefined) isDropAllowedMember = updates.isDropAllowedMember;
@@ -776,8 +808,10 @@
 		if (updates.selectedPaths !== undefined) selectedPaths = updates.selectedPaths;
 		if (updates.expandLevel !== undefined) expandLevel = updates.expandLevel;
 		if (updates.clickBehavior !== undefined) clickBehavior = updates.clickBehavior;
+		if (updates.selectionMode !== undefined) selectionMode = updates.selectionMode;
 		if (updates.showCheckboxes !== undefined) showCheckboxes = updates.showCheckboxes;
 		if (updates.checkboxMode !== undefined) checkboxMode = updates.checkboxMode;
+		if (updates.clickTogglesCheckbox !== undefined) clickTogglesCheckbox = updates.clickTogglesCheckbox;
 		if (updates.beforeCheckboxToggleCallback !== undefined) beforeCheckboxToggleCallback = updates.beforeCheckboxToggleCallback;
 		if (updates.rangeSelectionMode !== undefined) rangeSelectionMode = updates.rangeSelectionMode;
 		if (updates.shouldUseInternalSearchIndex !== undefined) shouldUseInternalSearchIndex = updates.shouldUseInternalSearchIndex;
@@ -837,6 +871,8 @@
 
 		let handled = true;
 
+		// Shift+nav extends the highlight range. In single mode the controller
+		// short-circuits these to no-ops (see _navHighlightTo).
 		switch (event.key) {
 			case 'ArrowDown':  event.shiftKey ? controller.navHighlightNext() : controller.navNextSibling(); break;
 			case 'ArrowUp':    event.shiftKey ? controller.navHighlightPrev() : controller.navPrevSibling(); break;
@@ -848,7 +884,19 @@
 			case 'PageDown':   event.shiftKey ? controller.navHighlightPageDown() : controller.navPageDown(); break;
 			case 'PageUp':     event.shiftKey ? controller.navHighlightPageUp() : controller.navPageUp(); break;
 			case 'Enter':
-			case ' ':          controller.navToggle(); break;
+				// single: no-op (per spec); multi: toggle highlight on focused node.
+				if (controller.selectionMode === 'multi') controller.toggleFocusedHighlight();
+				else handled = false;
+				break;
+			case ' ':
+				// With checkboxes: toggle the focused node's checkbox.
+				// Without: keep the legacy expand/collapse behaviour as a useful fallback.
+				if (controller.showCheckboxes && controller.focusedNode?.isSelectable) {
+					controller.nodeCallbacks.onCheckboxToggle(controller.focusedNode);
+				} else {
+					controller.navToggle();
+				}
+				break;
 			default:           handled = false;
 		}
 

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

@@ -1,6 +1,6 @@
 import type { Index, SearchOptions } from 'flexsearch';
 import { type LTreeNode } from '../ltree/ltree-node.svelte.js';
-import { type InsertArrayResult, type InsertBranchResult, type DeleteBranchResult, type ContextMenuEntry, type DropPosition, type DragDropMode, type DropOperation, type ClickBehavior, type CheckboxMode, type TreeChange, type ApplyChangesResult } from '../ltree/types.js';
+import { type InsertArrayResult, type InsertBranchResult, type DeleteBranchResult, type ContextMenuEntry, type DropPosition, type DragDropMode, type DropOperation, type ClickBehavior, type CheckboxMode, type SelectionMode, type TreeChange, type ApplyChangesResult } from '../ltree/types.js';
 import type { RenderStats } from './RenderCoordinator.svelte.js';
 import { TreeController } from '../core/TreeController.svelte.js';
 import type { TreeNavigationOverrides } from '../core/navigation.js';
@@ -11,8 +11,11 @@ declare function $$render<T>(): {
         parentPathMember?: string | null | undefined;
         levelMember?: string | null | undefined;
         isExpandedMember?: string | null | undefined;
+        getIsExpandedCallback?: (node: LTreeNode<T>) => boolean;
         isSelectableMember?: string | null | undefined;
+        getIsSelectableCallback?: (node: LTreeNode<T>) => boolean;
         isSelectedMember?: string | null | undefined;
+        getIsSelectedCallback?: (node: LTreeNode<T>) => boolean;
         isDraggableMember?: string | null | undefined;
         getIsDraggableCallback?: (node: LTreeNode<T>) => boolean;
         isDropAllowedMember?: string | null | undefined;
@@ -45,8 +48,16 @@ declare function $$render<T>(): {
         loadingPlaceholder?: any;
         expandLevel?: number | null | undefined;
         clickBehavior?: ClickBehavior | null | undefined;
+        /**
+         * `'single'` (default): plain click highlights one node; Ctrl/Shift+click
+         * degrade to plain click; Shift+Arrow / Enter are no-ops.
+         * `'multi'`: Ctrl-toggle, Shift-range, Shift+Arrow extend, Enter toggles
+         * highlight on the focused node.
+         */
+        selectionMode?: SelectionMode | null | undefined;
         showCheckboxes?: boolean | null | undefined;
         checkboxMode?: CheckboxMode | null | undefined;
+        clickTogglesCheckbox?: boolean | null | undefined;
         beforeCheckboxToggleCallback?: (node: LTreeNode<T>, checked: boolean, affectedPaths: string[]) => boolean | string[] | void;
         rangeSelectionMode?: "visual" | "logical";
         initializeIndexCallback?: () => Index;
@@ -221,8 +232,11 @@ declare function $$render<T>(): {
             parentPathMember?: string | null | undefined;
             levelMember?: string | null | undefined;
             isExpandedMember?: string | null | undefined;
+            getIsExpandedCallback?: (node: LTreeNode<T>) => boolean;
             isSelectableMember?: string | null | undefined;
+            getIsSelectableCallback?: (node: LTreeNode<T>) => boolean;
             isSelectedMember?: string | null | undefined;
+            getIsSelectedCallback?: (node: LTreeNode<T>) => boolean;
             isDraggableMember?: string | null | undefined;
             getIsDraggableCallback?: (node: LTreeNode<T>) => boolean;
             isDropAllowedMember?: string | null | undefined;
@@ -255,8 +269,16 @@ declare function $$render<T>(): {
             loadingPlaceholder?: any;
             expandLevel?: number | null | undefined;
             clickBehavior?: ClickBehavior | null | undefined;
+            /**
+             * `'single'` (default): plain click highlights one node; Ctrl/Shift+click
+             * degrade to plain click; Shift+Arrow / Enter are no-ops.
+             * `'multi'`: Ctrl-toggle, Shift-range, Shift+Arrow extend, Enter toggles
+             * highlight on the focused node.
+             */
+            selectionMode?: SelectionMode | null | undefined;
             showCheckboxes?: boolean | null | undefined;
             checkboxMode?: CheckboxMode | null | undefined;
+            clickTogglesCheckbox?: boolean | null | undefined;
             beforeCheckboxToggleCallback?: (node: LTreeNode<T>, checked: boolean, affectedPaths: string[]) => boolean | string[] | void;
             rangeSelectionMode?: "visual" | "logical";
             initializeIndexCallback?: () => Index;
@@ -342,7 +364,7 @@ declare function $$render<T>(): {
             onTreeKeydown?: (event: KeyboardEvent, controller: TreeController<T>) => boolean | void;
             /** Override individual navigation methods (e.g. for custom ArrowDown/Up behavior) */
             navigationOverrides?: TreeNavigationOverrides<T>;
-        }, "treeId" | "treePathSeparator" | "idMember" | "pathMember" | "parentPathMember" | "levelMember" | "hasChildrenMember" | "isExpandedMember" | "isSelectableMember" | "isSelectedMember" | "isDraggableMember" | "getIsDraggableCallback" | "isDropAllowedMember" | "displayValueMember" | "getDisplayValueCallback" | "searchValueMember" | "getSearchValueCallback" | "isCollapsibleMember" | "getIsCollapsibleCallback" | "orderMember" | "isSorted" | "sortCallback" | "data" | "focusedNode" | "highlightedPaths" | "selectedPaths" | "expandLevel" | "clickBehavior" | "showCheckboxes" | "checkboxMode" | "beforeCheckboxToggleCallback" | "rangeSelectionMode" | "shouldUseInternalSearchIndex" | "initializeIndexCallback" | "searchText" | "indexerBatchSize" | "indexerTimeout" | "shouldDisplayDebugInformation" | "shouldDisplayContextMenuInDebugMode" | "onNodeClick" | "onHighlightChange" | "onSelectionChange" | "onNodeDragStart" | "onNodeDragOver" | "onNodeDrop" | "beforeDropCallback" | "beforeCopyCallback" | "beforeCutCallback" | "beforePasteCallback" | "getContextMenuItemsCallback" | "virtualScroll" | "virtualRowHeight" | "virtualOverscan" | "virtualContainerHeight" | "dragDropMode" | "dropZoneMode" | "bodyClass" | "expandIconClass" | "collapseIconClass" | "leafIconClass" | "toggleIconMode" | "highlightedNodeClass" | "focusedNodeClass" | "dragOverNodeClass" | "scrollHighlightTimeout" | "scrollHighlightClass" | "contextMenuXOffset" | "contextMenuYOffset" | "accordionExpand">>) => void;
+        }, "treeId" | "treePathSeparator" | "idMember" | "pathMember" | "parentPathMember" | "levelMember" | "hasChildrenMember" | "isExpandedMember" | "getIsExpandedCallback" | "isSelectableMember" | "getIsSelectableCallback" | "isSelectedMember" | "getIsSelectedCallback" | "isDraggableMember" | "getIsDraggableCallback" | "isDropAllowedMember" | "displayValueMember" | "getDisplayValueCallback" | "searchValueMember" | "getSearchValueCallback" | "isCollapsibleMember" | "getIsCollapsibleCallback" | "orderMember" | "isSorted" | "sortCallback" | "data" | "focusedNode" | "highlightedPaths" | "selectedPaths" | "expandLevel" | "clickBehavior" | "selectionMode" | "showCheckboxes" | "checkboxMode" | "clickTogglesCheckbox" | "beforeCheckboxToggleCallback" | "rangeSelectionMode" | "shouldUseInternalSearchIndex" | "initializeIndexCallback" | "searchText" | "indexerBatchSize" | "indexerTimeout" | "shouldDisplayDebugInformation" | "shouldDisplayContextMenuInDebugMode" | "onNodeClick" | "onHighlightChange" | "onSelectionChange" | "onNodeDragStart" | "onNodeDragOver" | "onNodeDrop" | "beforeDropCallback" | "beforeCopyCallback" | "beforeCutCallback" | "beforePasteCallback" | "getContextMenuItemsCallback" | "virtualScroll" | "virtualRowHeight" | "virtualOverscan" | "virtualContainerHeight" | "dragDropMode" | "dropZoneMode" | "bodyClass" | "expandIconClass" | "collapseIconClass" | "leafIconClass" | "toggleIconMode" | "highlightedNodeClass" | "focusedNodeClass" | "dragOverNodeClass" | "scrollHighlightTimeout" | "scrollHighlightClass" | "contextMenuXOffset" | "contextMenuYOffset" | "accordionExpand">>) => void;
     };
     bindings: "data" | "focusedNode" | "highlightedPaths" | "selectedPaths" | "searchText" | "insertResult" | "isRendering";
     slots: {};
@@ -441,8 +463,11 @@ declare class __sveltets_Render<T> {
             parentPathMember?: string | null | undefined;
             levelMember?: string | null | undefined;
             isExpandedMember?: string | null | undefined;
+            getIsExpandedCallback?: ((node: LTreeNode<T>) => boolean) | undefined;
             isSelectableMember?: string | null | undefined;
+            getIsSelectableCallback?: ((node: LTreeNode<T>) => boolean) | undefined;
             isSelectedMember?: string | null | undefined;
+            getIsSelectedCallback?: ((node: LTreeNode<T>) => boolean) | undefined;
             isDraggableMember?: string | null | undefined;
             getIsDraggableCallback?: ((node: LTreeNode<T>) => boolean) | undefined;
             isDropAllowedMember?: string | null | undefined;
@@ -475,8 +500,16 @@ declare class __sveltets_Render<T> {
             loadingPlaceholder?: any;
             expandLevel?: number | null | undefined;
             clickBehavior?: ClickBehavior | null | undefined;
+            /**
+             * `'single'` (default): plain click highlights one node; Ctrl/Shift+click
+             * degrade to plain click; Shift+Arrow / Enter are no-ops.
+             * `'multi'`: Ctrl-toggle, Shift-range, Shift+Arrow extend, Enter toggles
+             * highlight on the focused node.
+             */
+            selectionMode?: SelectionMode | null | undefined;
             showCheckboxes?: boolean | null | undefined;
             checkboxMode?: CheckboxMode | null | undefined;
+            clickTogglesCheckbox?: boolean | null | undefined;
             beforeCheckboxToggleCallback?: ((node: LTreeNode<T>, checked: boolean, affectedPaths: string[]) => boolean | string[] | void) | undefined;
             rangeSelectionMode?: "visual" | "logical";
             initializeIndexCallback?: (() => Index) | undefined;
@@ -562,7 +595,7 @@ declare class __sveltets_Render<T> {
             onTreeKeydown?: ((event: KeyboardEvent, controller: TreeController<T>) => boolean | void) | undefined;
             /** Override individual navigation methods (e.g. for custom ArrowDown/Up behavior) */
             navigationOverrides?: Partial<import("../core/navigation.js").TreeNavigation<T>> | undefined;
-        }, "treeId" | "data" | "treePathSeparator" | "idMember" | "pathMember" | "parentPathMember" | "levelMember" | "hasChildrenMember" | "isExpandedMember" | "displayValueMember" | "getDisplayValueCallback" | "searchValueMember" | "getSearchValueCallback" | "orderMember" | "isSorted" | "sortCallback" | "isSelectableMember" | "isSelectedMember" | "isDraggableMember" | "getIsDraggableCallback" | "isDropAllowedMember" | "isCollapsibleMember" | "getIsCollapsibleCallback" | "shouldDisplayDebugInformation" | "onNodeDrop" | "beforeDropCallback" | "beforeCopyCallback" | "beforeCutCallback" | "beforePasteCallback" | "beforeCheckboxToggleCallback" | "getContextMenuItemsCallback" | "focusedNode" | "highlightedPaths" | "selectedPaths" | "expandLevel" | "clickBehavior" | "showCheckboxes" | "checkboxMode" | "rangeSelectionMode" | "initializeIndexCallback" | "searchText" | "shouldUseInternalSearchIndex" | "indexerBatchSize" | "indexerTimeout" | "shouldDisplayContextMenuInDebugMode" | "virtualScroll" | "virtualRowHeight" | "virtualOverscan" | "virtualContainerHeight" | "dragDropMode" | "dropZoneMode" | "accordionExpand" | "onNodeClick" | "onNodeDragStart" | "onNodeDragOver" | "onHighlightChange" | "onSelectionChange" | "bodyClass" | "highlightedNodeClass" | "focusedNodeClass" | "dragOverNodeClass" | "expandIconClass" | "collapseIconClass" | "leafIconClass" | "toggleIconMode" | "scrollHighlightTimeout" | "scrollHighlightClass" | "contextMenuXOffset" | "contextMenuYOffset">>) => void;
+        }, "treeId" | "data" | "treePathSeparator" | "idMember" | "pathMember" | "parentPathMember" | "levelMember" | "hasChildrenMember" | "isExpandedMember" | "getIsExpandedCallback" | "displayValueMember" | "getDisplayValueCallback" | "searchValueMember" | "getSearchValueCallback" | "orderMember" | "isSorted" | "sortCallback" | "isSelectableMember" | "getIsSelectableCallback" | "isSelectedMember" | "getIsSelectedCallback" | "isDraggableMember" | "getIsDraggableCallback" | "isDropAllowedMember" | "isCollapsibleMember" | "getIsCollapsibleCallback" | "shouldDisplayDebugInformation" | "onNodeDrop" | "beforeDropCallback" | "beforeCopyCallback" | "beforeCutCallback" | "beforePasteCallback" | "beforeCheckboxToggleCallback" | "getContextMenuItemsCallback" | "focusedNode" | "highlightedPaths" | "selectedPaths" | "expandLevel" | "clickBehavior" | "selectionMode" | "showCheckboxes" | "checkboxMode" | "clickTogglesCheckbox" | "rangeSelectionMode" | "initializeIndexCallback" | "searchText" | "shouldUseInternalSearchIndex" | "indexerBatchSize" | "indexerTimeout" | "shouldDisplayContextMenuInDebugMode" | "virtualScroll" | "virtualRowHeight" | "virtualOverscan" | "virtualContainerHeight" | "dragDropMode" | "dropZoneMode" | "accordionExpand" | "onNodeClick" | "onNodeDragStart" | "onNodeDragOver" | "onHighlightChange" | "onSelectionChange" | "bodyClass" | "highlightedNodeClass" | "focusedNodeClass" | "dragOverNodeClass" | "expandIconClass" | "collapseIconClass" | "leafIconClass" | "toggleIconMode" | "scrollHighlightTimeout" | "scrollHighlightClass" | "contextMenuXOffset" | "contextMenuYOffset">>) => void;
     };
 }
 interface $$IsomorphicComponent {

package/dist/constants.generated.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "5.0.0-rc08";
+export declare const VERSION = "5.0.0-rc09";
 export declare const PACKAGE_NAME = "@keenmate/svelte-treeview";
 export declare const AUTHOR = "KeenMate";
 export declare const LICENSE = "MIT";

package/dist/constants.generated.js

@@ -1,6 +1,6 @@
 // Auto-generated file - do not edit manually
 // Generated by scripts/generate-constants.js
-export const VERSION = "5.0.0-rc08";
+export const VERSION = "5.0.0-rc09";
 export const PACKAGE_NAME = "@keenmate/svelte-treeview";
 export const AUTHOR = "KeenMate";
 export const LICENSE = "MIT";