@warkypublic/svelix 0.1.47 → 0.2.1

package/dist/components/VTree/VTreeInteractionDemo.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 VTreeInteractionDemo: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type VTreeInteractionDemo = InstanceType<typeof VTreeInteractionDemo>;
+export default VTreeInteractionDemo;

package/dist/components/VTree/VTreeMultiSelectDemo.svelte

@@ -0,0 +1,27 @@
+<script lang="ts">import VTree from "./VTree.svelte";
+const data = [
+	{
+		id: "a",
+		label: "Alpha"
+	},
+	{
+		id: "b",
+		label: "Beta"
+	},
+	{
+		id: "c",
+		label: "Gamma"
+	}
+];
+let selectedItems = [];
+let selectionMode = "checkbox";
+</script>
+
+<div class="space-y-2">
+  <select bind:value={selectionMode}>
+    <option value="checkbox">checkbox</option>
+    <option value="modifier">modifier</option>
+  </select>
+  <VTree {data} multiple {selectionMode} {selectedItems} onSelectedItemsChange={(items) => selectedItems = items} searchable={false} />
+  <p class="text-xs">Selected: {selectedItems.map((item) => item.label).join(', ') || 'none'}</p>
+</div>

package/dist/components/VTree/VTreeMultiSelectDemo.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 VTreeMultiSelectDemo: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type VTreeMultiSelectDemo = InstanceType<typeof VTreeMultiSelectDemo>;
+export default VTreeMultiSelectDemo;

package/dist/components/VTree/VTreeRow.svelte

@@ -1,16 +1,50 @@
-<script lang="ts">const { row, index, rowHeight, indent, isFocused, isSelected, getNodeLabel, getNodeDescription, treeDataSnapshot, leftSection, rightSection, onselectrow, onrowdoubleclick, onrowcontext, ontogglerow } = $props();
-const rowClasses = $derived([
-	"grid grid-cols-[1fr_auto] items-center select-none border-b border-surface-200-700 hover:bg-surface-100-800",
-	isFocused ? "bg-primary-100 dark:bg-primary-900/35" : "",
-	isSelected ? "bg-primary-200 dark:bg-primary-900/60" : ""
-].join(" "));
+<script lang="ts">import { isImageLikeValue, mergeClasses } from "./VTree.utils.js";
+const { row, index, rowHeight, autoMeasure = false, indent, isFocused, isSelected, multiple = false, selectionMode = "modifier", isChecked = false, iconValue, icon, showRowSeparator = true, hoverEffect = true, classes, getNodeLabel, getNodeDescription, treeDataSnapshot, leftSection, rightSection, onselectrow, oncheckboxselect, onrowdoubleclick, onrowcontext, ontogglerow, onrowlongpress, onrowhover, onrowhoverend, longPressDelay = 500, longPressMoveTolerance = 10 } = $props();
+const DEFAULT_CLASSES = {
+	row: "grid grid-cols-[1fr_auto] items-center select-none",
+	rowSeparator: "border-b border-surface-200-700",
+	rowFocused: "bg-primary-100 dark:bg-primary-900/35",
+	rowSelected: "bg-primary-200 dark:bg-primary-900/60",
+	rowHover: "hover:bg-surface-100-800",
+	expandIcon: "inline-flex h-5 w-5 shrink-0 items-center justify-center rounded text-surface-700-200-token hover:bg-surface-200-700 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-500",
+	indentGuide: "min-w-0 flex items-center gap-1.5 pr-2 text-surface-900-100-token",
+	label: "truncate text-sm",
+	description: "truncate text-xs text-surface-500-400-token",
+	iconWrapper: "inline-flex h-5 w-5 shrink-0 items-center justify-center text-sm"
+};
+let longPressTimer;
+let startX = 0;
+let startY = 0;
+let suppressNextClick = false;
 const sectionArgs = $derived({
 	node: row.node,
 	level: row.level,
 	rowIndex: index,
 	treeData: treeDataSnapshot
 });
-export {};
+const rowClasses = $derived([
+	mergeClasses(DEFAULT_CLASSES.row, classes?.row),
+	showRowSeparator ? mergeClasses(DEFAULT_CLASSES.rowSeparator, classes?.rowSeparator) : "",
+	hoverEffect ? mergeClasses(DEFAULT_CLASSES.rowHover, classes?.rowHover) : "",
+	isFocused ? mergeClasses(DEFAULT_CLASSES.rowFocused, classes?.rowFocused) : "",
+	isSelected ? mergeClasses(DEFAULT_CLASSES.rowSelected, classes?.rowSelected) : ""
+].filter(Boolean).join(" "));
+function cancelLongPress() {
+	clearTimeout(longPressTimer);
+	longPressTimer = undefined;
+}
+function handlePointerDown(event) {
+	startX = event.clientX;
+	startY = event.clientY;
+	cancelLongPress();
+	longPressTimer = setTimeout(() => {
+		suppressNextClick = true;
+		onrowlongpress?.(index, event);
+	}, longPressDelay);
+}
+function handlePointerMove(event) {
+	if (Math.hypot(event.clientX - startX, event.clientY - startY) > longPressMoveTolerance) cancelLongPress();
+}
 </script>
 
 <div
@@ -20,65 +54,45 @@ export {};
   aria-expanded={row.hasChildren ? row.expanded : undefined}
   aria-selected={isSelected}
   tabindex="-1"
-  style={`height: ${rowHeight}px;`}
-  onclick={(event) => onselectrow?.(index, event)}
-  ondblclick={(event) => onrowdoubleclick?.(index, event)}
-  oncontextmenu={(event) => {
-    event.stopPropagation();
-    onrowcontext?.(index, event);
-  }}
-  onkeydown={(event) => {
-    if (event.key !== 'Enter' && event.key !== ' ') return;
-    event.preventDefault();
-    onselectrow?.(index, new MouseEvent('click'));
-    if (row.hasChildren) {
-      ontogglerow?.(row.node);
-    }
+  style={autoMeasure ? `min-height: ${rowHeight}px;` : `height: ${rowHeight}px;`}
+  onclick={(event) => {
+    if (suppressNextClick) { suppressNextClick = false; return; }
+    onselectrow?.(index, event);
   }}
+  ondblclick={(event) => onrowdoubleclick?.(index, event)}
+  oncontextmenu={(event) => { event.stopPropagation(); onrowcontext?.(index, event); }}
+  onkeydown={() => undefined}
+  onpointerdown={handlePointerDown}
+  onpointermove={handlePointerMove}
+  onpointerup={cancelLongPress}
+  onpointercancel={cancelLongPress}
+  onpointerenter={(event) => onrowhover?.(index, event)}
+  onpointerleave={(event) => { cancelLongPress(); onrowhoverend?.(index, event); }}
 >
-  <div
-    class="min-w-0 flex items-center gap-1.5 pr-2 text-surface-900-100-token"
-    style={`padding-left: ${(row.level - 1) * indent}px;`}
-  >
+  <div class={mergeClasses(DEFAULT_CLASSES.indentGuide, classes?.indentGuide)} style={`padding-left: ${(row.level - 1) * indent}px;`}>
     {#if leftSection}
-      <span class="inline-flex shrink-0 items-center">{@render leftSection(sectionArgs)}</span>
+      <span class="inline-flex shrink-0 items-center">
+        {@render leftSection(sectionArgs)}
+      </span>
     {/if}
-
     {#if row.hasChildren}
-      <button
-        class="inline-flex h-5 w-5 shrink-0 items-center justify-center rounded text-surface-700-200-token hover:bg-surface-200-700 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-500"
-        type="button"
-        aria-label={row.expanded ? 'Collapse node' : 'Expand node'}
-        onclick={(event) => {
-          event.stopPropagation();
-          ontogglerow?.(row.node);
-        }}
-      >
-        {#if row.loading}
-          <span
-            class="h-3 w-3 animate-spin rounded-full border-2 border-surface-400/30 border-t-surface-700 dark:border-surface-300/30 dark:border-t-surface-100"
-            aria-hidden="true"
-          ></span>
-        {:else}
-          {row.expanded ? '▾' : '▸'}
-        {/if}
+      <button class={mergeClasses(DEFAULT_CLASSES.expandIcon, classes?.expandIcon)} type="button" aria-label={row.expanded ? 'Collapse node' : 'Expand node'} onclick={(event) => { event.stopPropagation(); ontogglerow?.(row.node); }}>
+        {#if row.loading}<span class="h-3 w-3 animate-spin rounded-full border-2 border-surface-400/30 border-t-surface-700 dark:border-surface-300/30 dark:border-t-surface-100" aria-hidden="true"></span>{:else}{row.expanded ? '▾' : '▸'}{/if}
       </button>
-    {:else}
-      <span class="inline-flex h-5 w-5 shrink-0" aria-hidden="true"></span>
+    {:else}<span class="inline-flex h-5 w-5 shrink-0" aria-hidden="true"></span>{/if}
+    {#if multiple && selectionMode === 'checkbox'}
+      <input class="h-4 w-4 shrink-0" type="checkbox" checked={isChecked} aria-label={`Select ${getNodeLabel(row.node)}`} onclick={(event) => { event.stopPropagation(); oncheckboxselect?.(index, event); }} />
     {/if}
-
-    <span class="truncate text-sm" class:font-semibold={row.matched}>{getNodeLabel(row.node)}</span>
-    {#if getNodeDescription(row.node)}
-      <span class="truncate text-xs text-surface-500-400-token">{getNodeDescription(row.node)}</span>
+    {#if icon}
+      <span class={mergeClasses(DEFAULT_CLASSES.iconWrapper, classes?.iconWrapper)}>{@render icon(sectionArgs)}</span>
+    {:else if iconValue !== undefined && iconValue !== null && iconValue !== ''}
+      <span class={mergeClasses(DEFAULT_CLASSES.iconWrapper, classes?.iconWrapper)}>{#if isImageLikeValue(iconValue)}<img class="h-4 w-4 object-contain" src={String(iconValue)} alt="" />{:else}{String(iconValue)}{/if}</span>
     {/if}
+    <span class={mergeClasses(DEFAULT_CLASSES.label, classes?.label)} class:font-semibold={row.matched}>{getNodeLabel(row.node)}</span>
+    {#if getNodeDescription(row.node)}<span class={mergeClasses(DEFAULT_CLASSES.description, classes?.description)}>{getNodeDescription(row.node)}</span>{/if}
   </div>
-
   <div class="flex items-center gap-2 pr-2">
-    {#if row.error}
-      <span class="text-xs text-error-500">{row.error}</span>
-    {/if}
-    {#if rightSection}
-      <span class="inline-flex items-center">{@render rightSection(sectionArgs)}</span>
-    {/if}
+    {#if row.error}<span class="text-xs text-error-500">{row.error}</span>{/if}
+    {#if rightSection}<span class="inline-flex items-center">{@render rightSection(sectionArgs)}</span>{/if}
   </div>
 </div>

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

@@ -1,36 +1,52 @@
-import type { VTreeFlatRow } from './VTree.models.js';
-import type { VTreeRecord } from './types.js';
 import type { Snippet } from 'svelte';
+import type { VTreeFlatRow } from './VTree.models.js';
+import type { VTreeClassOverrides, VTreeRecord } from './types.js';
 export interface Props<T extends VTreeRecord = VTreeRecord> {
     row: VTreeFlatRow<T>;
     index: number;
     rowHeight: number;
+    autoMeasure?: boolean;
     indent: number;
     isFocused: boolean;
     isSelected: boolean;
+    multiple?: boolean;
+    selectionMode?: 'modifier' | 'checkbox';
+    isChecked?: boolean;
+    iconValue?: unknown;
+    icon?: Snippet<[{
+        node: T;
+        level: number;
+        rowIndex: number;
+        treeData: T[];
+    }]>;
+    showRowSeparator?: boolean;
+    hoverEffect?: boolean;
+    classes?: VTreeClassOverrides;
     getNodeLabel: (node: T) => string;
     getNodeDescription: (node: T) => string;
     treeDataSnapshot: T[];
-    leftSection?: Snippet<[
-        {
-            node: T;
-            level: number;
-            rowIndex: number;
-            treeData: T[];
-        }
-    ]>;
-    rightSection?: Snippet<[
-        {
-            node: T;
-            level: number;
-            rowIndex: number;
-            treeData: T[];
-        }
-    ]>;
+    leftSection?: Snippet<[{
+        node: T;
+        level: number;
+        rowIndex: number;
+        treeData: T[];
+    }]>;
+    rightSection?: Snippet<[{
+        node: T;
+        level: number;
+        rowIndex: number;
+        treeData: T[];
+    }]>;
     onselectrow?: (index: number, event: MouseEvent) => void;
+    oncheckboxselect?: (index: number, event: MouseEvent) => void;
     onrowdoubleclick?: (index: number, event: MouseEvent) => void;
     onrowcontext?: (index: number, event: MouseEvent) => void;
     ontogglerow?: (node: T) => void;
+    onrowlongpress?: (index: number, event: PointerEvent) => void;
+    onrowhover?: (index: number, event: PointerEvent) => void;
+    onrowhoverend?: (index: number, event: PointerEvent) => void;
+    longPressDelay?: number;
+    longPressMoveTolerance?: number;
 }
 declare const VTreeRow: import("svelte").Component<Props<VTreeRecord>, {}, "">;
 type VTreeRow = ReturnType<typeof VTreeRow>;

package/dist/components/VTree/VTreeVirtualViewport.svelte

@@ -1,14 +1,22 @@
 <script lang="ts">import { createVirtualizer } from "@tanstack/svelte-virtual";
 import VTreeRow from "./VTreeRow.svelte";
-const { rows, rowHeight, height, indent, overscan, focusedIndex, selectedId, loadingRoot, loadingMessage, emptyMessage, getNodeLabel, getNodeDescription, treeDataSnapshot, leftSection, rightSection, onselectrow, onrowdoubleclick, onrowcontext, onviewportcontext, ontogglerow, ontreekeydown } = $props();
+import { resolveRowHeight } from "./VTree.utils.js";
+const { rows, rowHeight, autoMeasure = false, height, indent, overscan, focusedIndex, selectedId, selectedNodeId, selectedItemIds = [], loadingRoot, loadingMessage, emptyMessage, multiple = false, selectionMode = "modifier", iconField, icon, classes, showRowSeparator = true, hoverEffect = true, getNodeLabel, getNodeDescription, treeDataSnapshot, leftSection, rightSection, onselectrow, oncheckboxselect, onrowdoubleclick, onrowcontext, onviewportcontext, ontogglerow, onrowlongpress, onrowhover, onrowhoverend, longPressDelay, longPressMoveTolerance, ontreekeydown } = $props();
 let viewportRef = $state(null);
 let virtualizerInstance = $state(null);
 function toCssSize(value) {
 	return typeof value === "number" ? `${value}px` : value;
 }
+function estimate(index) {
+	const row = rows[index];
+	return resolveRowHeight(rowHeight, row?.node, row?.level ?? 1, index);
+}
 export function scrollToIndex(index) {
 	virtualizerInstance?.scrollToIndex(index, { align: "auto" });
 }
+function measure(node) {
+	if (autoMeasure) virtualizerInstance?.measureElement(node);
+}
 $effect(() => {
 	if (!viewportRef) {
 		virtualizerInstance = null;
@@ -16,7 +24,7 @@ $effect(() => {
 	}
 	const virtualizer = createVirtualizer({
 		count: rows.length,
-		estimateSize: () => rowHeight,
+		estimateSize: estimate,
 		overscan,
 		getScrollElement: () => viewportRef
 	});
@@ -28,7 +36,7 @@ $effect(() => {
 	if (!virtualizerInstance || !viewportRef) return;
 	virtualizerInstance.setOptions({
 		count: rows.length,
-		estimateSize: () => rowHeight,
+		estimateSize: estimate,
 		overscan,
 		getScrollElement: () => viewportRef
 	});
@@ -37,49 +45,21 @@ const virtualItems = $derived(virtualizerInstance?.getVirtualItems() ?? []);
 const totalSize = $derived(virtualizerInstance?.getTotalSize() ?? 0);
 </script>
 
-<div
-  class="card overflow-auto border border-surface-300-700 bg-surface-50-950 focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500"
-  bind:this={viewportRef}
-  style={`height: ${toCssSize(height)};`}
-  onkeydown={(event) => ontreekeydown?.(event)}
-  oncontextmenu={(event) => onviewportcontext?.(event)}
-  tabindex="0"
-  role="tree"
-  aria-label="Virtual tree"
->
+<div class="card overflow-auto border border-surface-300-700 bg-surface-50-950 focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500" bind:this={viewportRef} style={`height: ${toCssSize(height)};`} onkeydown={(event) => ontreekeydown?.(event)} oncontextmenu={(event) => onviewportcontext?.(event)} tabindex="0" role="tree" aria-label="Virtual tree">
   {#if loadingRoot}
     <div class="grid min-h-24 place-items-center px-3 text-sm text-surface-500-400-token">{loadingMessage}</div>
   {:else if rows.length === 0}
     <div class="grid min-h-24 place-items-center px-3 text-sm text-surface-500-400-token">{emptyMessage}</div>
   {:else}
     <div class="relative w-full" style={`height: ${totalSize}px;`}>
-      <div
-        class="absolute left-0 top-0 w-full"
-        style={`transform: translateY(${virtualItems[0]?.start ?? 0}px);`}
-      >
-        {#each virtualItems as item (item.key)}
-          {@const row = rows[item.index]}
-          {#if row}
-            <VTreeRow
-              row={row}
-              index={item.index}
-              {rowHeight}
-              {indent}
-              isFocused={item.index === focusedIndex}
-              isSelected={row.id === selectedId}
-              {getNodeLabel}
-              {getNodeDescription}
-              {treeDataSnapshot}
-              {leftSection}
-              {rightSection}
-              {onselectrow}
-              {onrowdoubleclick}
-              {onrowcontext}
-              {ontogglerow}
-            />
-          {/if}
-        {/each}
-      </div>
+      {#each virtualItems as item (item.key)}
+        {@const row = rows[item.index]}
+        {#if row}
+          <div class="absolute left-0 top-0 w-full" style={`transform: translateY(${item.start}px);`} {@attach measure}>
+            <VTreeRow row={row} index={item.index} rowHeight={estimate(item.index)} {autoMeasure} {indent} isFocused={item.index === focusedIndex} isSelected={row.id === (selectedNodeId || selectedId)} {multiple} {selectionMode} isChecked={selectedItemIds.includes(row.id)} iconValue={iconField ? row.node[iconField] : undefined} {icon} {classes} {showRowSeparator} {hoverEffect} {getNodeLabel} {getNodeDescription} {treeDataSnapshot} {leftSection} {rightSection} {onselectrow} {oncheckboxselect} {onrowdoubleclick} {onrowcontext} {ontogglerow} {onrowlongpress} {onrowhover} {onrowhoverend} {longPressDelay} {longPressMoveTolerance} />
+          </div>
+        {/if}
+      {/each}
     </div>
   {/if}
 </div>

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

@@ -1,41 +1,58 @@
 import type { Snippet } from 'svelte';
 import type { VTreeFlatRow } from './VTree.models.js';
-import type { VTreeRecord } from './types.js';
+import type { VTreeClassOverrides, VTreeRecord } from './types.js';
 export interface Props<T extends VTreeRecord = VTreeRecord> {
     rows: VTreeFlatRow<T>[];
-    rowHeight: number;
+    rowHeight: number | ((node: T, level: number, index: number) => number);
+    autoMeasure?: boolean;
     height: string | number;
     indent: number;
     overscan: number;
     focusedIndex: number;
     selectedId: string | null;
+    selectedNodeId?: string;
+    selectedItemIds?: string[];
     loadingRoot: boolean;
     loadingMessage: string;
     emptyMessage: string;
+    multiple?: boolean;
+    selectionMode?: 'modifier' | 'checkbox';
+    iconField?: keyof T & string;
+    icon?: Snippet<[{
+        node: T;
+        level: number;
+        rowIndex: number;
+        treeData: T[];
+    }]>;
+    classes?: VTreeClassOverrides;
+    showRowSeparator?: boolean;
+    hoverEffect?: boolean;
     getNodeLabel: (node: T) => string;
     getNodeDescription: (node: T) => string;
     treeDataSnapshot: T[];
-    leftSection?: Snippet<[
-        {
-            node: T;
-            level: number;
-            rowIndex: number;
-            treeData: T[];
-        }
-    ]>;
-    rightSection?: Snippet<[
-        {
-            node: T;
-            level: number;
-            rowIndex: number;
-            treeData: T[];
-        }
-    ]>;
+    leftSection?: Snippet<[{
+        node: T;
+        level: number;
+        rowIndex: number;
+        treeData: T[];
+    }]>;
+    rightSection?: Snippet<[{
+        node: T;
+        level: number;
+        rowIndex: number;
+        treeData: T[];
+    }]>;
     onselectrow?: (index: number, event: MouseEvent) => void;
+    oncheckboxselect?: (index: number, event: MouseEvent) => void;
     onrowdoubleclick?: (index: number, event: MouseEvent) => void;
     onrowcontext?: (index: number, event: MouseEvent) => void;
     onviewportcontext?: (event: MouseEvent) => void;
     ontogglerow?: (node: T) => void;
+    onrowlongpress?: (index: number, event: PointerEvent) => void;
+    onrowhover?: (index: number, event: PointerEvent) => void;
+    onrowhoverend?: (index: number, event: PointerEvent) => void;
+    longPressDelay?: number;
+    longPressMoveTolerance?: number;
     ontreekeydown?: (event: KeyboardEvent) => void;
 }
 declare const VTreeVirtualViewport: import("svelte").Component<Props<VTreeRecord>, {

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

@@ -45,7 +45,8 @@ export interface VTreeProps<T extends VTreeRecord = VTreeRecord> {
     childrenField?: keyof T & string;
     hasChildrenField?: keyof T & string;
     height?: number | string;
-    rowHeight?: number;
+    rowHeight?: number | ((node: T, level: number, index: number) => number);
+    autoMeasure?: boolean;
     indent?: number;
     overscan?: number;
     searchable?: boolean;
@@ -80,4 +81,41 @@ export interface VTreeProps<T extends VTreeRecord = VTreeRecord> {
     ontoggle?: (node: T, expanded: boolean) => void;
     onsearch?: (query: string) => void;
     onloaderror?: (error: unknown, node?: T) => void;
+    iconField?: keyof T & string;
+    icon?: Snippet<[{
+        node: T;
+        level: number;
+        rowIndex: number;
+        treeData: T[];
+    }]>;
+    classes?: VTreeClassOverrides;
+    showRowSeparator?: boolean;
+    hoverEffect?: boolean;
+    /** Controlled single-selection. Undefined means uncontrolled; null means explicitly empty. */
+    selected?: T | null;
+    /** Enables selectedItems/onSelectedItemsChange multi-selection. */
+    multiple?: boolean;
+    selectionMode?: 'modifier' | 'checkbox';
+    onSelectedChange?: (node: T | null) => void;
+    selectedItems?: T[];
+    onSelectedItemsChange?: (items: T[]) => void;
+    onsingleclick?: (node: T, treeData: T[], event: MouseEvent) => void;
+    singleClickDelay?: number;
+    onlongpress?: (node: T, treeData: T[], event: PointerEvent) => void;
+    longPressDelay?: number;
+    longPressMoveTolerance?: number;
+    onrowhover?: (node: T, treeData: T[], rowIndex: number, event: PointerEvent) => void;
+    onrowhoverend?: (node: T, treeData: T[], rowIndex: number, event: PointerEvent) => void;
+}
+export interface VTreeClassOverrides {
+    row?: string;
+    rowSeparator?: string;
+    rowFocused?: string;
+    rowSelected?: string;
+    rowHover?: string;
+    expandIcon?: string;
+    indentGuide?: string;
+    label?: string;
+    description?: string;
+    iconWrapper?: string;
 }

package/llm/COMPONENT_GUIDE.md

@@ -130,6 +130,30 @@ The project now contains a mix of simple components, folder-based component modu
 </script>
 ```
 
+**⚠️ Guardrail — never read and write the same `$state` inside one effect**
+
+```svelte
+<script lang="ts">
+	// ❌ Infinite loop: .filter() always returns a NEW array reference, even
+	// when nothing was removed. The effect tracks its own write target, sees
+	// a "changed" value on every run, and reruns forever — Svelte throws
+	// effect_update_depth_exceeded ("reads and writes the same piece of state").
+	$effect(() => {
+		selected = selected.filter((item) => validIds.has(item.id));
+	});
+
+	// ✅ Read the current value via untrack() so the effect doesn't depend on
+	// its own write target, and only write when something actually changed.
+	$effect(() => {
+		const current = untrack(() => selected);
+		const next = current.filter((item) => validIds.has(item.id));
+		if (next.length !== current.length) selected = next;
+	});
+</script>
+```
+
+Same hazard applies to any derived-and-reassigned value, not just `.filter()`: object/array spreads (`{...x}`, `[...x]`), `new Set(x)` / `new Map(x)`, `.map()`, `.sort()` copies — anything producing a new reference even when the content is unchanged. Real-world case: `CardGrid.svelte`'s "Reconcile selection" effect.
+
 #### Snippet - Children/Slots
 ```svelte
 <script lang="ts">
@@ -1211,6 +1235,7 @@ Before considering a component complete:
 - [ ] Focus management is correct
 - [ ] Documented in stories (autodocs)
 - [ ] Re-exported from `src/lib/components/index.ts` and therefore reachable from `src/lib/index.ts`
+- [ ] No `$effect` reads and writes the same `$state` without `untrack()` / a change-guard (see $effect Guardrail above)
 
 ## Advanced Patterns