@warkypublic/svelix 0.1.47 → 0.2.2

package/dist/components/FormerControllers/NumberInputCtrl.svelte

@@ -1,25 +1,32 @@
-<script lang="ts">let { disabled, error, label, max, min, name, onchange, placeholder, required, sid, step, tooltip, value = $bindable(undefined) } = $props();
-const id = $derived(`field_${name ?? ""}_${sid ?? ""}`);
+<script lang="ts">import CtrlFieldShell from "./CtrlFieldShell.svelte";
+import { makeFieldId } from "./utils";
+let { disabled, error, label, max, min, name, onchange, placeholder, required, sid, step, tooltip, value = $bindable(undefined) } = $props();
+const id = $derived(makeFieldId(name, sid));
 function handleInput(e) {
 	const target = e.target;
-	const parsed = target.value !== "" ? Number(target.value) : undefined;
+	const raw = target.value;
+	if (raw === "") {
+		value = undefined;
+		onchange?.(undefined);
+		return;
+	}
+	const parsed = Number(raw);
+	// Intermediate typed states (e.g. "-", "1e") parse to NaN; ignore until valid.
+	if (Number.isNaN(parsed)) {
+		return;
+	}
 	value = parsed;
 	onchange?.(parsed);
 }
-export {};
 </script>
 
-<div class="flex flex-col gap-1" title={tooltip}>
-	{#if label}
-		<label class="label text-sm font-medium" for={id}>
-			{label}{#if required}<span class="text-error-500">*</span>{/if}
-		</label>
-	{/if}
+<CtrlFieldShell {error} {id} {label} {required} {tooltip}>
 	<input
 		{id}
 		{disabled}
 		{max}
 		{min}
+		{name}
 		{placeholder}
 		{required}
 		{step}
@@ -29,7 +36,4 @@ export {};
 		value={value ?? ''}
 		oninput={handleInput}
 	/>
-	{#if error}
-		<p class="text-error-500 text-xs">{error}</p>
-	{/if}
-</div>
+</CtrlFieldShell>

package/dist/components/FormerControllers/PasswordInputCtrl.svelte

@@ -1,19 +1,16 @@
-<script lang="ts">let { disabled, error, label, name, onchange, placeholder, required, sid, tooltip, value = $bindable("") } = $props();
-const id = $derived(`field_${name ?? ""}_${sid ?? ""}`);
+<script lang="ts">import CtrlFieldShell from "./CtrlFieldShell.svelte";
+import { makeFieldId } from "./utils";
+let { disabled, error, label, name, onchange, placeholder, required, sid, tooltip, value = $bindable("") } = $props();
+const id = $derived(makeFieldId(name, sid));
 let showPassword = $state(false);
-export {};
 </script>
 
-<div class="flex flex-col gap-1" title={tooltip}>
-	{#if label}
-		<label class="label text-sm font-medium" for={id}>
-			{label}{#if required}<span class="text-error-500">*</span>{/if}
-		</label>
-	{/if}
+<CtrlFieldShell {error} {id} {label} {required} {tooltip}>
 	<div class="flex gap-0">
 		<input
 			{id}
 			{disabled}
+			{name}
 			{placeholder}
 			{required}
 			bind:value
@@ -32,7 +29,4 @@ export {};
 			{showPassword ? '🙈' : '👁'}
 		</button>
 	</div>
-	{#if error}
-		<p class="text-error-500 text-xs">{error}</p>
-	{/if}
-</div>
+</CtrlFieldShell>

package/dist/components/FormerControllers/SwitchCtrl.svelte

@@ -1,12 +1,13 @@
-<script lang="ts">let { checked = $bindable(false), disabled, error, label, name, onchange, sid, tooltip } = $props();
-const id = $derived(`field_${name ?? ""}_${sid ?? ""}`);
-export {};
+<script lang="ts">import { makeFieldId } from "./utils";
+let { checked = $bindable(false), disabled, error, label, name, onchange, sid, tooltip } = $props();
+const id = $derived(makeFieldId(name, sid));
 </script>
 
 <div class="flex items-center gap-2" title={tooltip}>
 	<input
 		{id}
 		{disabled}
+		{name}
 		bind:checked
 		class="checkbox"
 		type="checkbox"

package/dist/components/FormerControllers/TextAreaCtrl.svelte

@@ -1,17 +1,14 @@
-<script lang="ts">let { disabled, error, label, name, onchange, placeholder, required, rows = 4, sid, tooltip, value = $bindable("") } = $props();
-const id = $derived(`field_${name ?? ""}_${sid ?? ""}`);
-export {};
+<script lang="ts">import CtrlFieldShell from "./CtrlFieldShell.svelte";
+import { makeFieldId } from "./utils";
+let { disabled, error, label, name, onchange, placeholder, required, rows = 4, sid, tooltip, value = $bindable("") } = $props();
+const id = $derived(makeFieldId(name, sid));
 </script>
 
-<div class="flex flex-col gap-1" title={tooltip}>
-	{#if label}
-		<label class="label text-sm font-medium" for={id}>
-			{label}{#if required}<span class="text-error-500">*</span>{/if}
-		</label>
-	{/if}
+<CtrlFieldShell {error} {id} {label} {required} {tooltip}>
 	<textarea
 		{id}
 		{disabled}
+		{name}
 		{placeholder}
 		{required}
 		{rows}
@@ -20,7 +17,4 @@ export {};
 		class:textarea-error={!!error}
 		oninput={() => onchange?.(value)}
 	></textarea>
-	{#if error}
-		<p class="text-error-500 text-xs">{error}</p>
-	{/if}
-</div>
+</CtrlFieldShell>

package/dist/components/FormerControllers/TextInputCtrl.svelte

@@ -1,17 +1,14 @@
-<script lang="ts">let { disabled, error, label, name, onchange, placeholder, required, sid, tooltip, type = "text", value = $bindable("") } = $props();
-const id = $derived(`field_${name ?? ""}_${sid ?? ""}`);
-export {};
+<script lang="ts">import CtrlFieldShell from "./CtrlFieldShell.svelte";
+import { makeFieldId } from "./utils";
+let { disabled, error, label, name, onchange, placeholder, required, sid, tooltip, type = "text", value = $bindable("") } = $props();
+const id = $derived(makeFieldId(name, sid));
 </script>
 
-<div class="flex flex-col gap-1" title={tooltip}>
-	{#if label}
-		<label class="label text-sm font-medium" for={id}>
-			{label}{#if required}<span class="text-error-500">*</span>{/if}
-		</label>
-	{/if}
+<CtrlFieldShell {error} {id} {label} {required} {tooltip}>
 	<input
 		{id}
 		{disabled}
+		{name}
 		{placeholder}
 		{required}
 		{type}
@@ -20,7 +17,4 @@ export {};
 		class:input-error={!!error}
 		oninput={() => onchange?.(value)}
 	/>
-	{#if error}
-		<p class="text-error-500 text-xs">{error}</p>
-	{/if}
-</div>
+</CtrlFieldShell>

package/dist/components/FormerControllers/ctrlLoading.svelte.d.ts

@@ -0,0 +1,8 @@
+export declare function createClickLoading(getExternalLoading: () => boolean | undefined): {
+    readonly isLoading: boolean;
+    run: (action?: () => Promise<void>) => Promise<void>;
+};
+export declare function createClickPulse(durationMs?: number): {
+    readonly pressed: boolean;
+    trigger: () => void;
+};

package/dist/components/FormerControllers/ctrlLoading.svelte.js

@@ -0,0 +1,43 @@
+export function createClickLoading(getExternalLoading) {
+    let internalLoading = $state(false);
+    const isLoading = $derived(internalLoading || (getExternalLoading() ?? false));
+    async function run(action) {
+        if (!action || isLoading)
+            return;
+        internalLoading = true;
+        try {
+            await action();
+        }
+        finally {
+            internalLoading = false;
+        }
+    }
+    return {
+        get isLoading() {
+            return isLoading;
+        },
+        run,
+    };
+}
+// Guarantees a visible "click" pulse even when the action resolves faster than
+// a human can perceive the loading spinner — decoupled from actual duration.
+export function createClickPulse(durationMs = 200) {
+    let pressed = $state(false);
+    let timeout;
+    function trigger() {
+        pressed = true;
+        clearTimeout(timeout);
+        timeout = setTimeout(() => {
+            pressed = false;
+        }, durationMs);
+    }
+    $effect(() => {
+        return () => clearTimeout(timeout);
+    });
+    return {
+        get pressed() {
+            return pressed;
+        },
+        trigger,
+    };
+}

package/dist/components/FormerControllers/index.d.ts

@@ -1,4 +1,5 @@
 export { default as ButtonCtrl } from './ButtonCtrl.svelte';
+export { default as CtrlFieldShell } from './CtrlFieldShell.svelte';
 export { DateTimeCtrl } from './DateTimeCtrl/index';
 export { default as IconButtonCtrl } from './IconButtonCtrl.svelte';
 export { default as InlineWrapper } from './InlineWrapper.svelte';
@@ -8,5 +9,6 @@ export { default as PasswordInputCtrl } from './PasswordInputCtrl.svelte';
 export { default as SwitchCtrl } from './SwitchCtrl.svelte';
 export { default as TextAreaCtrl } from './TextAreaCtrl.svelte';
 export { default as TextInputCtrl } from './TextInputCtrl.svelte';
+export { makeFieldId } from './utils';
 export type { DateTimeConstraints, DateTimeMode, DateTimeParts } from './DateTimeCtrl/DateTimeCtrl.utils';
 export * from './types';

package/dist/components/FormerControllers/index.js

@@ -1,4 +1,5 @@
 export { default as ButtonCtrl } from './ButtonCtrl.svelte';
+export { default as CtrlFieldShell } from './CtrlFieldShell.svelte';
 export { DateTimeCtrl } from './DateTimeCtrl/index';
 export { default as IconButtonCtrl } from './IconButtonCtrl.svelte';
 export { default as InlineWrapper } from './InlineWrapper.svelte';
@@ -8,4 +9,5 @@ export { default as PasswordInputCtrl } from './PasswordInputCtrl.svelte';
 export { default as SwitchCtrl } from './SwitchCtrl.svelte';
 export { default as TextAreaCtrl } from './TextAreaCtrl.svelte';
 export { default as TextInputCtrl } from './TextInputCtrl.svelte';
+export { makeFieldId } from './utils';
 export * from './types';

package/dist/components/FormerControllers/utils.d.ts

@@ -0,0 +1 @@
+export declare function makeFieldId(name?: string, sid?: string): string;

package/dist/components/FormerControllers/utils.js

@@ -0,0 +1,3 @@
+export function makeFieldId(name, sid) {
+    return `field_${name ?? ''}_${sid ?? ''}`;
+}

package/dist/components/Gridler/components/Gridler.svelte

@@ -10,12 +10,18 @@ const resolvedRowMarkers = $derived(rowMarkers ?? (settings?.showRowMarkers ? se
 // ── Theme ─────────────────────────────────────────────────────────────────────
 let isDarkMode = $state(false);
 let resolvedSkeletonTheme = $state(DEFAULT_THEME);
+// Both isDarkMode and resolvedSkeletonTheme are derived from a local `dark`
+// value rather than read back from isDarkMode itself, so this effect never
+// tracks its own write target — avoids tearing down/recreating the
+// MutationObserver on an incidental extra run.
 $effect(() => {
-	isDarkMode = detectDarkMode();
-	resolvedSkeletonTheme = resolveSkeletonGridTheme(isDarkMode) ?? (isDarkMode ? DEFAULT_THEME_DARK : DEFAULT_THEME);
+	const dark = detectDarkMode();
+	isDarkMode = dark;
+	resolvedSkeletonTheme = resolveSkeletonGridTheme(dark) ?? (dark ? DEFAULT_THEME_DARK : DEFAULT_THEME);
 	const mo = new MutationObserver(() => {
-		isDarkMode = detectDarkMode();
-		resolvedSkeletonTheme = resolveSkeletonGridTheme(isDarkMode) ?? (isDarkMode ? DEFAULT_THEME_DARK : DEFAULT_THEME);
+		const dark = detectDarkMode();
+		isDarkMode = dark;
+		resolvedSkeletonTheme = resolveSkeletonGridTheme(dark) ?? (dark ? DEFAULT_THEME_DARK : DEFAULT_THEME);
 	});
 	const opts = {
 		attributes: true,

package/dist/components/Gridler/components/GridlerFull.svelte

@@ -8,6 +8,7 @@ import { reorderColumns } from "../utils/columns.js";
 import { applyLocalFilter, buildSearchFilters, gridColumnFiltersToFilterOptions } from "../utils/filters.js";
 import { applyLocalSort, sortOrderToSortOptions } from "../utils/sort.js";
 import { makeGetCellContent } from "../utils/cellContent.js";
+import { getServerRenderableRows } from "../utils/serverPaging.js";
 let { columns, data, getCellContent, rows, manageColumns = true, onColumnsChange, searchValue, defaultSearchValue = "", onSearchValueChange, onDataChange, dataSource, dataSourceOptions, pageSize = 200, uniqueID, serverSideSearch = false, searchColumns, onLoadError, total = $bindable(0), loading = $bindable(false), filters, onFilterChange, sortOrder, onSortOrderChange, selectedItems: _selectedItems, onSelectedItemsChange, settings, fixedColumns = 0, rowMarkers, showSearch, height = 500, onColumnMoved, onCellEdited, onCellDblClick, onRowDblClick, onRowClick, onRowContextMenu, onMenuClick, onSelectionChange, onCellEvent, onGridEvent, menuItems, onMenuItemSelect, children, ...rest } = $props();
 // ── Column management ─────────────────────────────────────────────────────
 // eslint-disable-next-line svelte/no-unused-svelte-ignore
@@ -471,7 +472,7 @@ const resolvedGetCellContent = $derived.by(() => {
 });
 // ── Row count ──────────────────────────────────────────────────────────────
 const resolvedRows = $derived.by(() => {
-	if (isServerMode) return serverTotal;
+	if (isServerMode) return getServerRenderableRows(serverData.length, serverTotal, serverAllLoaded);
 	if (rows != null) return rows;
 	return filteredDataState.length;
 });

package/dist/components/Gridler/utils/serverPaging.d.ts

@@ -0,0 +1 @@
+export declare function getServerRenderableRows(loadedRows: number, reportedTotal: number, allLoaded: boolean): number;

package/dist/components/Gridler/utils/serverPaging.js

@@ -0,0 +1,7 @@
+export function getServerRenderableRows(loadedRows, reportedTotal, allLoaded) {
+    if (allLoaded)
+        return reportedTotal;
+    if (reportedTotal <= 0)
+        return loadedRows;
+    return Math.min(loadedRows, reportedTotal);
+}

package/dist/components/VTree/VTree.svelte

@@ -2,7 +2,8 @@
 import VTreeSearch from "./VTreeSearch.svelte";
 import VTreeVirtualViewport from "./VTreeVirtualViewport.svelte";
 import VTreeContextMenu from "./VTreeContextMenu.svelte";
-const { data = [], adapter, idField = "id", labelField = "label", descriptionField = "description", childrenField = "children", hasChildrenField = "hasChildren", height = 420, rowHeight = 36, indent = 18, overscan = 8, searchable = true, searchPlaceholder = "Search tree...", searchValue = "", serverSideSearch = false, autoExpandSearchResults = true, loadOnMount = true, emptyMessage = "Nothing here...", loadingMessage = "Loading...", leftSection, rightSection, contextMenuItems, onselect, onclick, ondoubleclick, oncontext, ontoggle, onsearch, onloaderror } = $props();
+import { buildNodeIndex, computeMultiSelectClick, findAncestorIds } from "./VTree.utils.js";
+const { data = [], adapter, idField = "id", labelField = "label", descriptionField = "description", childrenField = "children", hasChildrenField = "hasChildren", height = 420, rowHeight = 36, indent = 18, overscan = 8, searchable = true, searchPlaceholder = "Search tree...", searchValue = "", serverSideSearch = false, autoExpandSearchResults = true, loadOnMount = true, emptyMessage = "Nothing here...", loadingMessage = "Loading...", leftSection, rightSection, contextMenuItems, onselect, onclick, ondoubleclick, oncontext, ontoggle, onsearch, onloaderror, selected, onSelectedChange, multiple = false, selectedItems, onSelectedItemsChange, selectionMode = "modifier", autoMeasure = false, iconField, icon, classes, showRowSeparator = true, hoverEffect = true, onsingleclick, singleClickDelay = 250, onlongpress, longPressDelay = 500, longPressMoveTolerance = 10, onrowhover, onrowhoverend } = $props();
 let viewportRef = $state(undefined);
 let focusedIndex = $state(0);
 let selectedId = $state(null);
@@ -22,6 +23,50 @@ let contextX = $state(0);
 let contextY = $state(0);
 let contextRow = $state(null);
 let contextItems = $state([]);
+// Long-press is handled per row and committed here when fired.
+function handleRowLongpress(index, event) {
+	const row = flattenedRows[index];
+	if (!row) return;
+	selectRow(index);
+	commitSelection(index);
+	onlongpress?.(row.node, treeDataSnapshot, event);
+}
+// Selection model state.
+let internalSelected = $state(null);
+let internalSelectedItems = $state([]);
+let rangeAnchorIndex = $state(null);
+let lastRevealedId = $state(null);
+let lastScrolledId = $state(null);
+let singleClickTimer;
+let clickCount = 0;
+function commitSelection(index, event, forceToggle = false) {
+	const row = flattenedRows[index];
+	if (!row) return;
+	if (multiple) {
+		applyMultiSelect(row.node, index, event, forceToggle);
+	} else {
+		onSelectedChange?.(row.node);
+		if (selected === undefined) internalSelected = row.node;
+	}
+}
+function applyMultiSelect(node, index, event, forceToggle = false) {
+	const currentItems = selectedItems ?? internalSelectedItems;
+	const orderedRowIds = flattenedRows.map((row) => row.id);
+	const clickedId = getNodeId(node);
+	const result = computeMultiSelectClick({
+		currentIds: currentItems.map((item) => getNodeId(item)),
+		clickedId,
+		clickedIndex: index,
+		anchorIndex: rangeAnchorIndex,
+		orderedRowIds,
+		ctrlOrMeta: forceToggle || Boolean(event?.ctrlKey || event?.metaKey),
+		shift: Boolean(event?.shiftKey)
+	});
+	rangeAnchorIndex = result.nextAnchorIndex;
+	const items = result.ids.map((id) => nodeIndex.byId.get(id)).filter((item) => Boolean(item));
+	if (selectedItems === undefined) internalSelectedItems = items;
+	onSelectedItemsChange?.(items);
+}
 function getNodeId(node) {
 	const value = node?.[idField];
 	return String(value ?? "");
@@ -122,6 +167,7 @@ const displayRoots = $derived.by(() => {
 	if (adapter && serverSideSearch && searchQuery.trim().length > 0) return searchNodes;
 	return rootNodes;
 });
+const nodeIndex = $derived.by(() => buildNodeIndex(displayRoots, getNodeId, getNodeChildren));
 const flattenedRows = $derived.by(() => {
 	const rows = [];
 	const activeSearch = searchQuery.trim().toLowerCase();
@@ -178,10 +224,36 @@ const treeDataSnapshot = $derived.by(() => {
 	});
 	return buildTree(displayRoots);
 });
+const selectedNodeId = $derived(selected ? getNodeId(selected) : selected === null ? "" : internalSelected ? getNodeId(internalSelected) : "");
+$effect(() => {
+	if (!selectedNodeId || lastRevealedId === selectedNodeId) return;
+	const ancestors = findAncestorIds(nodeIndex.parentById, selectedNodeId);
+	const next = { ...expandedById };
+	let changed = false;
+	for (const id of ancestors) {
+		if (!next[id]) {
+			next[id] = true;
+			changed = true;
+		}
+	}
+	if (changed) expandedById = next;
+	lastRevealedId = selectedNodeId;
+	lastScrolledId = null;
+});
+$effect(() => {
+	if (!selectedNodeId || lastScrolledId === selectedNodeId) return;
+	const index = flattenedRows.findIndex((row) => row.id === selectedNodeId);
+	if (index < 0) return;
+	focusedIndex = index;
+	selectedId = selectedNodeId;
+	viewportRef?.scrollToIndex(index);
+	lastScrolledId = selectedNodeId;
+});
 function selectRow(index) {
 	const row = flattenedRows[index];
 	if (!row) return;
 	focusedIndex = index;
+	// Keep existing uncontrolled fallback behavior.
 	selectedId = row.id;
 	onselect?.(row.node);
 	viewportRef?.scrollToIndex(index);
@@ -247,13 +319,20 @@ function handleTreeKeydown(event) {
 		}
 		return;
 	}
-	if (event.key === " " || event.key === "Enter") {
+	if (event.key === "Enter") {
 		event.preventDefault();
 		selectRow(focusedIndex);
+		// Single-click selection via Enter.
+		commitSelection(focusedIndex);
 		if (current.hasChildren) {
 			toggleNode(current.node);
 		}
 	}
+	// Single-click selection via Space.
+	if (event.key === " ") {
+		event.preventDefault();
+		commitSelection(focusedIndex);
+	}
 }
 async function runServerSearch(query) {
 	if (!adapter || !serverSideSearch) return;
@@ -281,10 +360,20 @@ function handleRowClick(index, event) {
 	if (!row) return;
 	selectRow(index);
 	onclick?.(row.node, treeDataSnapshot, event);
+	// Checkbox mode intentionally leaves row-body clicks out of multi-selection.
+	if (!multiple || selectionMode === "modifier") commitSelection(index, event);
+	clearTimeout(singleClickTimer);
+	clickCount += 1;
+	singleClickTimer = setTimeout(() => {
+		if (clickCount === 1) onsingleclick?.(row.node, treeDataSnapshot, event);
+		clickCount = 0;
+	}, singleClickDelay);
 }
 function handleRowDoubleClick(index, event) {
 	const row = flattenedRows[index];
 	if (!row) return;
+	clearTimeout(singleClickTimer);
+	clickCount = 0;
 	selectRow(index);
 	ondoubleclick?.(row.node, treeDataSnapshot, event);
 }
@@ -358,6 +447,7 @@ onMount(() => {
     bind:this={viewportRef}
     rows={flattenedRows}
     {rowHeight}
+    {autoMeasure}
     {height}
     {indent}
     {overscan}
@@ -371,12 +461,27 @@ onMount(() => {
     {treeDataSnapshot}
     {leftSection}
     {rightSection}
+    {iconField}
+    {icon}
+    {classes}
+    {showRowSeparator}
+    {hoverEffect}
+    {multiple}
+    {selectionMode}
+    selectedItemIds={(selectedItems ?? internalSelectedItems).map((item) => getNodeId(item))}
+    selectedNodeId={selectedNodeId}
     onselectrow={handleRowClick}
     onrowdoubleclick={handleRowDoubleClick}
     onrowcontext={handleRowContext}
     onviewportcontext={handleViewportContext}
     ontogglerow={toggleNode}
     ontreekeydown={handleTreeKeydown}
+    onrowlongpress={handleRowLongpress}
+    oncheckboxselect={(index, event) => commitSelection(index, event, true)}
+    onrowhover={(index, event) => { const row = flattenedRows[index]; if (row) onrowhover?.(row.node, treeDataSnapshot, index, event); }}
+    onrowhoverend={(index, event) => { const row = flattenedRows[index]; if (row) onrowhoverend?.(row.node, treeDataSnapshot, index, event); }}
+    {longPressDelay}
+    {longPressMoveTolerance}
   />
 
   <VTreeContextMenu

package/dist/components/VTree/VTree.utils.d.ts

@@ -0,0 +1,23 @@
+import type { VTreeRecord } from './types.js';
+export interface NodeIndex<T extends VTreeRecord = VTreeRecord> {
+    byId: Map<string, T>;
+    parentById: Map<string, string | null>;
+}
+export declare function mergeClasses(base: string, override?: string): string;
+export declare function buildNodeIndex<T extends VTreeRecord>(roots: T[], getId: (node: T) => string, getChildren: (node: T) => T[]): NodeIndex<T>;
+export declare function findAncestorIds(parentById: Map<string, string | null>, targetId: string): string[];
+export declare function resolveRowHeight<T extends VTreeRecord>(rowHeight: number | ((node: T, level: number, index: number) => number), node: T | undefined, level: number, index: number, fallback?: number): number;
+export interface MultiSelectClickInput {
+    currentIds: string[];
+    clickedId: string;
+    clickedIndex: number;
+    anchorIndex: number | null;
+    orderedRowIds: string[];
+    ctrlOrMeta?: boolean;
+    shift?: boolean;
+}
+export declare function computeMultiSelectClick(input: MultiSelectClickInput): {
+    ids: string[];
+    nextAnchorIndex: number;
+};
+export declare function isImageLikeValue(value: unknown): boolean;

package/dist/components/VTree/VTree.utils.js

@@ -0,0 +1,73 @@
+export function mergeClasses(base, override) {
+    return [base, override].filter(Boolean).join(' ');
+}
+export function buildNodeIndex(roots, getId, getChildren) {
+    const byId = new Map();
+    const parentById = new Map();
+    const visiting = new Set();
+    const walk = (nodes, parentId) => {
+        for (const node of nodes) {
+            if (!node || visiting.has(node))
+                continue;
+            const id = getId(node);
+            if (!id || byId.has(id))
+                continue;
+            byId.set(id, node);
+            parentById.set(id, parentId);
+            visiting.add(node);
+            walk(getChildren(node), id);
+            visiting.delete(node);
+        }
+    };
+    walk(roots, null);
+    return { byId, parentById };
+}
+export function findAncestorIds(parentById, targetId) {
+    const visited = new Set();
+    const ancestors = [];
+    let current = targetId;
+    while (current && !visited.has(current)) {
+        visited.add(current);
+        const parent = parentById.get(current);
+        if (!parent)
+            break;
+        ancestors.push(parent);
+        current = parent;
+    }
+    return ancestors.reverse();
+}
+export function resolveRowHeight(rowHeight, node, level, index, fallback = 36) {
+    const value = typeof rowHeight === 'function' ? (node ? rowHeight(node, level, index) : fallback) : rowHeight;
+    return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+export function computeMultiSelectClick(input) {
+    const current = new Set(input.currentIds);
+    let ids;
+    const anchor = input.anchorIndex ?? input.clickedIndex;
+    if (input.shift) {
+        const start = Math.max(0, Math.min(anchor, input.clickedIndex));
+        const end = Math.min(input.orderedRowIds.length - 1, Math.max(anchor, input.clickedIndex));
+        ids = input.ctrlOrMeta ? new Set(current) : new Set();
+        for (const id of input.orderedRowIds.slice(start, end + 1))
+            ids.add(id);
+    }
+    else if (input.ctrlOrMeta) {
+        ids = new Set(current);
+        if (ids.has(input.clickedId))
+            ids.delete(input.clickedId);
+        else
+            ids.add(input.clickedId);
+    }
+    else {
+        ids = new Set([input.clickedId]);
+    }
+    return {
+        ids: input.orderedRowIds.filter((id) => ids.has(id)),
+        nextAnchorIndex: input.clickedIndex
+    };
+}
+export function isImageLikeValue(value) {
+    if (typeof value !== 'string')
+        return false;
+    return /^(https?:\/\/|data:image\/|\/|\.\/|\.\.\/).+\.(png|jpe?g|gif|svg|webp)(\?.*)?$/i.test(value) || /^data:image\//i.test(value);
+}

package/dist/components/VTree/VTreeControlledSelectionDemo.svelte

@@ -0,0 +1,20 @@
+<script lang="ts">import VTree from "./VTree.svelte";
+const data = [{
+	id: "root",
+	label: "Root",
+	children: [{
+		id: "deep",
+		label: "Deep child",
+		children: [{
+			id: "leaf",
+			label: "Leaf"
+		}]
+	}]
+}];
+let selected = null;
+</script>
+
+<div class="space-y-2">
+  <button class="btn preset-filled-primary-500" type="button" onclick={() => selected = data[0].children[0].children[0]}>Select leaf</button>
+  <VTree {data} {selected} onSelectedChange={(node) => selected = node} searchable={false} />
+</div>

package/dist/components/VTree/VTreeControlledSelectionDemo.svelte.d.ts

@@ -0,0 +1,18 @@
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const VTreeControlledSelectionDemo: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type VTreeControlledSelectionDemo = InstanceType<typeof VTreeControlledSelectionDemo>;
+export default VTreeControlledSelectionDemo;

package/dist/components/VTree/VTreeCustomizationDemo.svelte

@@ -0,0 +1,23 @@
+<script lang="ts">// @ts-nocheck
+import VTree from "./VTree.svelte";
+const data = [{
+	id: "folder",
+	label: "Folder",
+	icon: "📁",
+	children: [{
+		id: "doc",
+		label: "Document",
+		icon: "📄"
+	}]
+}, {
+	id: "settings",
+	label: "Settings",
+	icon: "⚙️"
+}];
+</script>
+
+{#snippet customIcon({ node })}
+  <span aria-hidden="true">{node.id === 'folder' ? '🗂️' : '✨'}</span>
+{/snippet}
+
+<VTree {data} iconField="icon" icon={customIcon} searchable={false} />