@keenmate/svelte-treeview 5.0.0-rc07 → 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'; });
@@ -507,20 +531,32 @@
 	);
 
 	// ── Export public methods (thin proxies) ────────────────────────────
-	export async function expandNodes(nodePath: string) {
-		controller.expandNodes(nodePath);
+	export async function expandNodes(
+		nodePath: string | string[],
+		options?: { exclusive?: boolean; noEmit?: boolean }
+	) {
+		controller.expandNodes(nodePath, options);
 	}
 
-	export async function collapseNodes(nodePath: string) {
-		controller.collapseNodes(nodePath);
+	export async function collapseNodes(
+		nodePath: string | string[],
+		options?: { noEmit?: boolean }
+	) {
+		controller.collapseNodes(nodePath, options);
 	}
 
-	export function expandAll(nodePath?: string | null | undefined) {
-		controller.expandAll(nodePath);
+	export function expandAll(
+		nodePath?: string | string[] | null | undefined,
+		options?: { exclusive?: boolean; noEmit?: boolean }
+	) {
+		controller.expandAll(nodePath, options);
 	}
 
-	export function collapseAll(nodePath?: string | null | undefined) {
-		controller.collapseAll(nodePath);
+	export function collapseAll(
+		nodePath?: string | string[] | null | undefined,
+		options?: { noEmit?: boolean }
+	) {
+		controller.collapseAll(nodePath, options);
 	}
 
 	export function filterNodes(searchTextVal: string, searchOptions?: SearchOptions): void {
@@ -613,16 +649,28 @@
 	}
 
 	// Multi-select methods
-	export function selectNode(path: string, mode: 'replace' | 'toggle' | 'range' = 'replace') {
-		controller.selectNode(path, mode);
+	export function selectNode(path: string, mode: 'replace' | 'toggle' | 'range' = 'replace', options?: { silent?: boolean }) {
+		controller.selectNode(path, mode, options);
 	}
 
-	export function selectNodes(paths: string[]) {
-		controller.selectNodes(paths);
+	export function selectNodes(paths: string[], options?: { silent?: boolean }) {
+		controller.selectNodes(paths, options);
 	}
 
-	export function deselectAll() {
-		controller.deselectAll();
+	export function highlightNode(path: string, mode: 'replace' | 'toggle' | 'range' = 'replace', options?: { silent?: boolean }) {
+		controller.highlightNode(path, mode, options);
+	}
+
+	export function highlightNodes(paths: string[], options?: { silent?: boolean }) {
+		controller.highlightNodes(paths, options);
+	}
+
+	export function clearHighlight(options?: { silent?: boolean }) {
+		controller.clearHighlight(options);
+	}
+
+	export function deselectAll(options?: { silent?: boolean }) {
+		controller.deselectAll(options);
 	}
 
 	export function getSelectedNodes(): LTreeNode<T>[] {
@@ -659,8 +707,11 @@
 				| "levelMember"
 				| "hasChildrenMember"
 				| "isExpandedMember"
+				| "getIsExpandedCallback"
 				| "isSelectableMember"
+				| "getIsSelectableCallback"
 				| "isSelectedMember"
+				| "getIsSelectedCallback"
 				| "isDraggableMember"
 				| "getIsDraggableCallback"
 				| "isDropAllowedMember"
@@ -679,8 +730,10 @@
 				| "selectedPaths"
 				| "expandLevel"
 				| "clickBehavior"
+				| "selectionMode"
 				| "showCheckboxes"
 				| "checkboxMode"
+				| "clickTogglesCheckbox"
 				| "beforeCheckboxToggleCallback"
 				| "rangeSelectionMode"
 				| "shouldUseInternalSearchIndex"
@@ -732,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;
@@ -752,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;
@@ -813,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;
@@ -824,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;
 		}