@marianmeres/stuic 3.66.1 → 3.68.0

package/dist/components/Input/FieldSelect.svelte

@@ -3,11 +3,11 @@
 	import type { HTMLSelectAttributes } from "svelte/elements";
 	import type { ValidateOptions } from "../../actions/validate.svelte.js";
 	import type { THC } from "../Thc/Thc.svelte";
-	import type { FieldSelectOption } from "./types.js";
+	import type { FieldSelectOption, InputWrapClassProps } from "./types.js";
 
 	type SnippetWithId = Snippet<[{ id: string }]>;
 
-	export interface Props extends HTMLSelectAttributes {
+	export interface Props extends HTMLSelectAttributes, InputWrapClassProps {
 		input?: HTMLSelectElement;
 		value?: string | number;
 		label?: SnippetWithId | THC;
@@ -28,13 +28,8 @@
 		labelLeft?: boolean;
 		labelLeftWidth?: "normal" | "wide";
 		labelLeftBreakpoint?: number;
+		/** Classes for the <select> element */
 		classInput?: string;
-		classLabel?: string;
-		classLabelBox?: string;
-		classInputBox?: string;
-		classInputBoxWrap?: string;
-		classDescBox?: string;
-		classBelowBox?: string;
 		style?: string;
 	}
 </script>
@@ -82,8 +77,11 @@
 		classLabelBox,
 		classInputBox,
 		classInputBoxWrap,
+		classInputBoxWrapInvalid,
 		classDescBox,
+		classDescBoxToggle,
 		classBelowBox,
+		classValidationBox,
 		style,
 		//
 		...rest
@@ -128,8 +126,11 @@
 	{classLabelBox}
 	{classInputBox}
 	{classInputBoxWrap}
+	{classInputBoxWrapInvalid}
 	{classDescBox}
+	{classDescBoxToggle}
 	{classBelowBox}
+	{classValidationBox}
 	{validation}
 	{style}
 >

package/dist/components/Input/FieldSelect.svelte.d.ts

@@ -2,11 +2,11 @@ import type { Snippet } from "svelte";
 import type { HTMLSelectAttributes } from "svelte/elements";
 import type { ValidateOptions } from "../../actions/validate.svelte.js";
 import type { THC } from "../Thc/Thc.svelte";
-import type { FieldSelectOption } from "./types.js";
+import type { FieldSelectOption, InputWrapClassProps } from "./types.js";
 type SnippetWithId = Snippet<[{
     id: string;
 }]>;
-export interface Props extends HTMLSelectAttributes {
+export interface Props extends HTMLSelectAttributes, InputWrapClassProps {
     input?: HTMLSelectElement;
     value?: string | number;
     label?: SnippetWithId | THC;
@@ -27,13 +27,8 @@ export interface Props extends HTMLSelectAttributes {
     labelLeft?: boolean;
     labelLeftWidth?: "normal" | "wide";
     labelLeftBreakpoint?: number;
+    /** Classes for the <select> element */
     classInput?: string;
-    classLabel?: string;
-    classLabelBox?: string;
-    classInputBox?: string;
-    classInputBoxWrap?: string;
-    classDescBox?: string;
-    classBelowBox?: string;
     style?: string;
 }
 declare const FieldSelect: import("svelte").Component<Props, {}, "value" | "input">;

package/dist/components/Input/FieldSwitch.svelte

@@ -2,10 +2,11 @@
 	import type { Snippet } from "svelte";
 	import type { ValidateOptions } from "../../actions/validate.svelte.js";
 	import type { THC } from "../Thc/Thc.svelte";
+	import type { InputWrapClassProps } from "./types.js";
 
 	type SnippetWithId = Snippet<[{ id: string }]>;
 
-	export interface Props extends Record<string, any> {
+	export interface Props extends InputWrapClassProps, Record<string, any> {
 		input?: HTMLInputElement;
 		checked?: boolean;
 		label?: SnippetWithId | THC;
@@ -27,13 +28,8 @@
 		labelLeft?: boolean;
 		labelLeftWidth?: "normal" | "wide";
 		labelLeftBreakpoint?: number;
+		/** Classes for the underlying <Switch> element */
 		classInput?: string;
-		classLabel?: string;
-		classLabelBox?: string;
-		classInputBox?: string;
-		classInputBoxWrap?: string;
-		classDescBox?: string;
-		classBelowBox?: string;
 		style?: string;
 		renderValue?: (rawValue: any) => string;
 	}
@@ -79,8 +75,11 @@
 		classLabelBox,
 		classInputBox,
 		classInputBoxWrap,
+		classInputBoxWrapInvalid,
 		classDescBox,
+		classDescBoxToggle,
 		classBelowBox,
+		classValidationBox,
 		style = "",
 		//
 		renderValue,
@@ -111,8 +110,11 @@
 	{classLabel}
 	{classLabelBox}
 	{classInputBox}
+	{classInputBoxWrapInvalid}
 	{classDescBox}
+	{classDescBoxToggle}
 	{classBelowBox}
+	{classValidationBox}
 	{validation}
 	classInputBoxWrap={twMerge("input-wrap-transparent", classInputBoxWrap)}
 	{style}

package/dist/components/Input/FieldSwitch.svelte.d.ts

@@ -1,10 +1,11 @@
 import type { Snippet } from "svelte";
 import type { ValidateOptions } from "../../actions/validate.svelte.js";
 import type { THC } from "../Thc/Thc.svelte";
+import type { InputWrapClassProps } from "./types.js";
 type SnippetWithId = Snippet<[{
     id: string;
 }]>;
-export interface Props extends Record<string, any> {
+export interface Props extends InputWrapClassProps, Record<string, any> {
     input?: HTMLInputElement;
     checked?: boolean;
     label?: SnippetWithId | THC;
@@ -26,13 +27,8 @@ export interface Props extends Record<string, any> {
     labelLeft?: boolean;
     labelLeftWidth?: "normal" | "wide";
     labelLeftBreakpoint?: number;
+    /** Classes for the underlying <Switch> element */
     classInput?: string;
-    classLabel?: string;
-    classLabelBox?: string;
-    classInputBox?: string;
-    classInputBoxWrap?: string;
-    classDescBox?: string;
-    classBelowBox?: string;
     style?: string;
     renderValue?: (rawValue: any) => string;
 }

package/dist/components/Input/FieldTextarea.svelte

@@ -3,10 +3,11 @@
 	import type { HTMLTextareaAttributes } from "svelte/elements";
 	import type { ValidateOptions } from "../../actions/validate.svelte.js";
 	import type { THC } from "../Thc/Thc.svelte";
+	import type { InputWrapClassProps } from "./types.js";
 
 	type SnippetWithId = Snippet<[{ id: string }]>;
 
-	export interface Props extends HTMLTextareaAttributes {
+	export interface Props extends HTMLTextareaAttributes, InputWrapClassProps {
 		input?: HTMLTextAreaElement;
 		value?: string;
 		label?: SnippetWithId | THC;
@@ -28,14 +29,8 @@
 		labelLeft?: boolean;
 		labelLeftWidth?: "normal" | "wide";
 		labelLeftBreakpoint?: number;
+		/** Classes for the <textarea> element */
 		classInput?: string;
-		classLabel?: string;
-		classLabelBox?: string;
-		classInputBox?: string;
-		classInputBoxWrap?: string;
-		classInputBoxWrapInvalid?: string;
-		classDescBox?: string;
-		classBelowBox?: string;
 		style?: string;
 	}
 </script>
@@ -85,7 +80,9 @@
 		classInputBoxWrap,
 		classInputBoxWrapInvalid,
 		classDescBox,
+		classDescBoxToggle,
 		classBelowBox,
+		classValidationBox,
 		style,
 		//
 		...rest
@@ -117,7 +114,9 @@
 	{classInputBoxWrap}
 	{classInputBoxWrapInvalid}
 	{classDescBox}
+	{classDescBoxToggle}
 	{classBelowBox}
+	{classValidationBox}
 	{validation}
 	{style}
 >

package/dist/components/Input/FieldTextarea.svelte.d.ts

@@ -2,10 +2,11 @@ import type { Snippet } from "svelte";
 import type { HTMLTextareaAttributes } from "svelte/elements";
 import type { ValidateOptions } from "../../actions/validate.svelte.js";
 import type { THC } from "../Thc/Thc.svelte";
+import type { InputWrapClassProps } from "./types.js";
 type SnippetWithId = Snippet<[{
     id: string;
 }]>;
-export interface Props extends HTMLTextareaAttributes {
+export interface Props extends HTMLTextareaAttributes, InputWrapClassProps {
     input?: HTMLTextAreaElement;
     value?: string;
     label?: SnippetWithId | THC;
@@ -30,14 +31,8 @@ export interface Props extends HTMLTextareaAttributes {
     labelLeft?: boolean;
     labelLeftWidth?: "normal" | "wide";
     labelLeftBreakpoint?: number;
+    /** Classes for the <textarea> element */
     classInput?: string;
-    classLabel?: string;
-    classLabelBox?: string;
-    classInputBox?: string;
-    classInputBoxWrap?: string;
-    classInputBoxWrapInvalid?: string;
-    classDescBox?: string;
-    classBelowBox?: string;
     style?: string;
 }
 declare const FieldTextarea: import("svelte").Component<Props, {}, "value" | "input">;

package/dist/components/Input/README.md

@@ -48,6 +48,26 @@ A comprehensive form input system with multiple field components, validation sup
 | `inputBelow`  | `Snippet \| THC` | Content below input                   |
 | `below`       | `Snippet \| THC` | Content below entire field            |
 
+## Shared wrapper class props (`InputWrapClassProps`)
+
+Every `Field*` component that uses the shared label/input/description scaffolding accepts **the same 9 class props**, exported as the `InputWrapClassProps` interface from `@marianmeres/stuic`. Each Field extends that interface in its own `Props`, so the shape stays in sync and new wrapper targets are added in one place.
+
+| Prop                        | Target                                                             |
+| --------------------------- | ------------------------------------------------------------------ |
+| `classLabel`                | `<label>` element                                                  |
+| `classLabelBox`             | Wrapper around the label area                                      |
+| `classInputBox`             | Wrapper around the whole input area                                |
+| `classInputBoxWrap`         | Inner input wrap (sibling to description/validation/below)         |
+| `classInputBoxWrapInvalid`  | Added to `classInputBoxWrap` when validation fails                 |
+| `classDescBox`              | Description/help text box                                          |
+| `classDescBoxToggle`        | Collapsible description's toggle button                            |
+| `classBelowBox`             | "Below" slot (rendered under the description)                      |
+| `classValidationBox`        | Validation message box                                             |
+
+Component-specific targets (e.g. `classInput` for the inner `<input>`/`<select>`/`<textarea>`, `classFileList` on `FieldFile`, `classOption`/`classOptgroup` on `FieldOptions`, `classPrefixTrigger` on `FieldPhoneNumber`, etc.) live on the component itself alongside these shared props.
+
+> `FieldCheckbox` and `FieldRadios` have bespoke inline layouts and don't use the shared wrapper — they declare only the class props relevant to their own layout.
+
 ## Usage
 
 ### Basic Text Input

package/dist/components/Input/_internal/InputWrap.svelte

@@ -5,10 +5,11 @@
 	import { twMerge } from "../../../utils/tw-merge.js";
 	import { Collapsible } from "../../Collapsible/index.js";
 	import Thc, { isTHCNotEmpty, type THC } from "../../Thc/Thc.svelte";
+	import type { InputWrapClassProps } from "../types.js";
 
 	type SnippetWithId = Snippet<[{ id: string }]>;
 
-	interface Props {
+	interface Props extends InputWrapClassProps {
 		id: string;
 		size?: "sm" | "md" | "lg" | string;
 		class?: string;
@@ -28,15 +29,6 @@
 		labelLeftWidth?: "normal" | "wide";
 		labelLeftBreakpoint?: number;
 		//
-		classLabel?: string;
-		classLabelBox?: string;
-		classInputBox?: string;
-		classInputBoxWrap?: string;
-		classInputBoxWrapInvalid?: string;
-		classDescBox?: string;
-		classDescBoxToggle?: string;
-		classBelowBox?: string;
-		classValidationBox?: string;
 		descriptionCollapsible?: boolean;
 		descriptionDefaultExpanded?: boolean;
 		style?: string;

package/dist/components/Input/_internal/InputWrap.svelte.d.ts

@@ -1,10 +1,11 @@
 import type { Snippet } from "svelte";
 import type { ValidationResult } from "../../../actions/validate.svelte.js";
 import { type THC } from "../../Thc/Thc.svelte";
+import type { InputWrapClassProps } from "../types.js";
 type SnippetWithId = Snippet<[{
     id: string;
 }]>;
-interface Props {
+interface Props extends InputWrapClassProps {
     id: string;
     size?: "sm" | "md" | "lg" | string;
     class?: string;
@@ -22,15 +23,6 @@ interface Props {
     labelLeft?: boolean;
     labelLeftWidth?: "normal" | "wide";
     labelLeftBreakpoint?: number;
-    classLabel?: string;
-    classLabelBox?: string;
-    classInputBox?: string;
-    classInputBoxWrap?: string;
-    classInputBoxWrapInvalid?: string;
-    classDescBox?: string;
-    classDescBoxToggle?: string;
-    classBelowBox?: string;
-    classValidationBox?: string;
     descriptionCollapsible?: boolean;
     descriptionDefaultExpanded?: boolean;
     style?: string;

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

@@ -9,3 +9,31 @@ export interface FieldRadiosOption {
     value?: string;
     description?: THC;
 }
+/**
+ * Class props forwarded to the shared `InputWrap` scaffolding used by every
+ * `Field*` component that has a label/input/description layout.
+ *
+ * Field components extend this interface in their own `Props` so the class-prop
+ * shape stays consistent across the library. Component-specific class props
+ * (e.g. `classInput`, `classFileList`, `classOption`) live on the component itself.
+ */
+export interface InputWrapClassProps {
+    /** Classes for the <label> element */
+    classLabel?: string;
+    /** Classes for the wrapper around the label area */
+    classLabelBox?: string;
+    /** Classes for the wrapper around the input area (contains input + inputBefore/After/Below) */
+    classInputBox?: string;
+    /** Classes for the inner input wrap (sibling to description/validation/below) */
+    classInputBoxWrap?: string;
+    /** Extra classes applied to `classInputBoxWrap` when the field is invalid */
+    classInputBoxWrapInvalid?: string;
+    /** Classes for the description box (the subtle hint below the input) */
+    classDescBox?: string;
+    /** Classes for the description's collapsible toggle button */
+    classDescBoxToggle?: string;
+    /** Classes for the "below" slot — rendered under the description */
+    classBelowBox?: string;
+    /** Classes for the validation message box */
+    classValidationBox?: string;
+}

package/dist/components/Nav/Nav.svelte

@@ -11,9 +11,9 @@
 		id: string;
 		/** Display label (supports localization) */
 		label: MaybeLocalized;
-		/** Navigation URL (use href OR onClick, not both) */
+		/** Navigation URL. If both `href` and `onClick` are provided, `onClick` runs first (useful for analytics) and the browser then follows the href. */
 		href?: string;
-		/** Click handler (alternative to href) */
+		/** Click handler. Alternative to `href`, or runs before navigation if both are set. */
 		onClick?: () => void;
 		/** Icon content (THC for flexibility: string, html, component) */
 		icon?: THC;
@@ -603,7 +603,7 @@
 										class={twMerge(!unstyled && NAV_CHILDREN_CLASSES, classChildren)}
 										transition:slide={{ duration: transitionDuration }}
 									>
-										{#each item.children ?? [] as child}
+										{#each item.children ?? [] as child (child.id)}
 											{@render renderItem(child, depth + 1)}
 										{/each}
 									</ul>
@@ -627,6 +627,7 @@
 									data-expanding={!unstyled && isExpanding ? "" : undefined}
 									data-disabled={!unstyled && item.disabled ? "" : undefined}
 									data-touch-friendly={!unstyled && isTouchFriendly ? "" : undefined}
+									aria-current={active ? "page" : undefined}
 									aria-disabled={item.disabled}
 									tabindex={item.disabled ? -1 : 0}
 									use:tooltip={() => ({
@@ -691,7 +692,7 @@
 						</li>
 					{/snippet}
 
-					{#each group.items ?? [] as item}
+					{#each group.items ?? [] as item (item.id)}
 						{@render renderItem(item, 0)}
 					{/each}
 				</ul>

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

@@ -9,9 +9,9 @@ export interface NavItem {
     id: string;
     /** Display label (supports localization) */
     label: MaybeLocalized;
-    /** Navigation URL (use href OR onClick, not both) */
+    /** Navigation URL. If both `href` and `onClick` are provided, `onClick` runs first (useful for analytics) and the browser then follows the href. */
     href?: string;
-    /** Click handler (alternative to href) */
+    /** Click handler. Alternative to `href`, or runs before navigation if both are set. */
     onClick?: () => void;
     /** Icon content (THC for flexibility: string, html, component) */
     icon?: THC;

package/dist/components/Nav/README.md

@@ -48,8 +48,8 @@ interface NavGroup {
 	items?: NavItem[];
 	/** Group icon (optional) */
 	icon?: THC;
-	/** Whether the group starts collapsed */
-	defaultCollapsed?: boolean;
+	/** Whether the group starts expanded (default: false — groups are collapsed by default) */
+	defaultExpanded?: boolean;
 	/** Navigation URL for groups without items */
 	href?: string;
 	/** Click handler for groups without items */

package/dist/components/Nav/index.css

@@ -66,6 +66,10 @@
 	--stuic-nav-item-text-focus: var(--stuic-color-primary-foreground);
 }
 
+:root.dark {
+	--stuic-nav-item-bg-hover: rgb(255 255 255 / 0.08);
+}
+
 @layer components {
 	/* =============================================================================
 	   BASE CONTAINER

package/dist/components/Tree/README.md

@@ -0,0 +1,189 @@
+# Tree
+
+A generic hierarchical tree view with drag-and-drop reordering, keyboard navigation, expand/collapse state, optional `localStorage` persistence, and full ARIA `treeview` semantics.
+
+Backed by [`@marianmeres/tree`](https://www.npmjs.com/package/@marianmeres/tree) for the data model — pass `tree.toJSON().children` or any compatible `TreeNodeDTO[]`.
+
+## Usage
+
+### Basic
+
+```svelte
+<script lang="ts">
+	import { Tree } from "@marianmeres/stuic";
+
+	const items = [
+		{
+			id: "root",
+			value: "Projects",
+			children: [
+				{ id: "a", value: "Alpha", children: [] },
+				{ id: "b", value: "Beta", children: [] },
+			],
+		},
+	];
+</script>
+
+<Tree {items} activeId="a" onSelect={(item) => console.log(item.id)} />
+```
+
+### Drag & Drop
+
+```svelte
+<Tree
+	{items}
+	draggable
+	onMove={({ source, target, position }) => {
+		// Mutate your data to move `source` relative to `target`.
+		// Return `false` (or throw) to reject the move.
+		moveNode(source.id, target.id, position);
+	}}
+	isDraggable={(item) => !item.data?.locked}
+	isDropTarget={(item) => item.data?.acceptsChildren !== false}
+/>
+```
+
+`onMove` receives `{ source, target, position: "before" | "after" | "inside" }`. The component does **not** mutate items itself — you own the data. Return `false` or throw to reject.
+
+### Expansion Control
+
+Four priority tiers resolve a node's initial expansion state, highest wins:
+
+1. `localStorage` value (when `persistState={true}`)
+2. `expandedIds` prop (explicit initial set)
+3. Auto-expanded if any descendant is active
+4. `defaultExpanded` prop
+
+```svelte
+<Tree
+	{items}
+	defaultExpanded
+	persistState
+	storageKeyPrefix="my-app-tree"
+	onToggle={(item, expanded) => console.log(item.id, expanded)}
+/>
+```
+
+Collapsing a branch also collapses all of its descendants.
+
+### Custom Rendering
+
+```svelte
+<Tree {items}>
+	{#snippet renderIcon(item, depth, isExpanded)}
+		<MyIcon type={item.data.kind} />
+	{/snippet}
+	{#snippet renderItem(item, depth, isExpanded)}
+		<span class="font-medium">{item.value}</span>
+		{#if item.data?.count}
+			<span class="ml-auto text-xs opacity-60">{item.data.count}</span>
+		{/if}
+	{/snippet}
+</Tree>
+```
+
+## Props
+
+| Prop                | Type                                                 | Default           | Description                                                              |
+| ------------------- | ---------------------------------------------------- | ----------------- | ------------------------------------------------------------------------ |
+| `items`             | `TreeNodeDTO<T>[]`                                   | required          | Tree data (e.g. from `tree.toJSON().children`)                           |
+| `activeId`          | `string`                                             | -                 | ID of the currently active/selected node                                 |
+| `isActive`          | `(item) => boolean`                                  | -                 | Alternative to `activeId` for custom active detection                    |
+| `onSelect`          | `(item) => void`                                     | -                 | Called when a node is selected (click or Enter/Space)                    |
+| `onToggle`          | `(item, expanded) => void`                           | -                 | Called when a branch is expanded/collapsed                               |
+| `sort`              | `(a, b) => number`                                   | -                 | Per-level sort comparator                                                |
+| `defaultExpanded`   | `boolean`                                            | `false`           | Default expansion state for branches                                     |
+| `expandedIds`       | `Set<string>`                                        | -                 | Initially-expanded branch IDs                                            |
+| `persistState`      | `boolean`                                            | `false`           | Persist expand/collapse to `localStorage`                                |
+| `storageKeyPrefix`  | `string`                                             | `"stuic-tree"`    | Prefix used for `localStorage` keys                                      |
+| `draggable`         | `boolean`                                            | `false`           | Enable drag-and-drop reordering                                          |
+| `isDraggable`       | `(item) => boolean`                                  | -                 | Return `false` to block dragging a specific node                         |
+| `isDropTarget`      | `(item) => boolean`                                  | -                 | Return `false` to block dropping onto a specific node                    |
+| `onMove`            | `(event) => void \| false \| Promise<void \| false>` | -                 | Called when a valid drop happens; return `false` to reject               |
+| `onError`           | `(err) => void`                                      | -                 | Called when `onMove` throws                                              |
+| `dragExpandDelay`   | `number`                                             | `800`             | ms before auto-expanding a collapsed branch hovered during drag          |
+| `t`                 | `TranslateFn`                                        | built-in          | Optional translation function (used for drag-drop a11y announcements)    |
+| `getNodeLabel`      | `(item) => string`                                   | `String(v.value)` | String used in a11y announcements when a node is moved                   |
+| `renderItem`        | `Snippet<[item, depth, isExpanded]>`                 | -                 | Custom node label renderer                                               |
+| `renderIcon`        | `Snippet<[item, depth, isExpanded]>`                 | -                 | Custom node icon renderer                                                |
+| `unstyled`          | `boolean`                                            | `false`           | Skip default styling                                                     |
+| `class`             | `string`                                             | -                 | Classes for wrapper                                                      |
+| `classItem`         | `string`                                             | -                 | Classes for each item button                                             |
+| `classItemActive`   | `string`                                             | -                 | Extra classes when an item is active                                     |
+| `classIcon`         | `string`                                             | -                 | Classes for the icon wrapper                                             |
+| `classLabel`        | `string`                                             | -                 | Classes for the label wrapper                                            |
+| `classChevron`      | `string`                                             | -                 | Classes for the expand/collapse chevron                                  |
+| `classChildren`     | `string`                                             | -                 | Classes for the children container                                       |
+| `el`                | `HTMLElement`                                        | -                 | Bindable wrapper reference                                               |
+
+## Keyboard Navigation
+
+| Key                   | Action                                                                |
+| --------------------- | --------------------------------------------------------------------- |
+| `ArrowDown`           | Focus next visible node                                               |
+| `ArrowUp`             | Focus previous visible node                                           |
+| `ArrowRight`          | Expand a collapsed branch, or move to first child of an expanded one  |
+| `ArrowLeft`           | Collapse an expanded branch, or move to parent                        |
+| `Home`                | Focus first visible node                                              |
+| `End`                 | Focus last visible node                                               |
+| `Enter` / `Space`     | Toggle expansion (if branch) and fire `onSelect`                      |
+
+Focus follows the **roving tabindex** pattern: only the currently-focused node has `tabindex=0`, all others are `-1`.
+
+## Accessibility
+
+- Root has `role="tree"`; each node has `role="treeitem"`.
+- Branches have `aria-expanded`; active nodes have `aria-selected`; all nodes have `aria-level`.
+- Children wrappers have `role="group"`.
+- Successful `onMove` calls announce the change via a visually-hidden `aria-live="polite"` region. Translate via the `t` prop — keys: `move_before`, `move_after`, `move_inside` with `{source}` and `{target}` placeholders.
+
+### Drag-drop limitations
+
+HTML5 drag-and-drop is **mouse-only** and not keyboard accessible. Touch support is device-dependent and unreliable. If keyboard/touch reordering matters for your app, layer your own UI on top (e.g. a context menu with "Move up / Move down / Move into…" actions that call your move logic directly).
+
+## CSS Variables
+
+Override globally in `:root` or locally via `style=""`. Radius / border-width / transition use the standard STUIC fallback pattern and inherit from their shared structural tokens unless overridden.
+
+### Structure
+
+| Variable                           | Default                  | Description                       |
+| ---------------------------------- | ------------------------ | --------------------------------- |
+| `--stuic-tree-indent`              | `1.25rem`                | Indentation per depth level       |
+| `--stuic-tree-item-padding-x`      | `0.375rem`               | Item horizontal padding           |
+| `--stuic-tree-item-padding-y`      | `0.125rem`               | Item vertical padding             |
+| `--stuic-tree-item-height`         | `1.75rem`                | Item row height                   |
+| `--stuic-tree-item-font-size`      | `var(--text-sm)`         | Item font size                    |
+| `--stuic-tree-item-gap`            | `0.25rem`                | Gap between chevron, icon, label  |
+| `--stuic-tree-chevron-size`        | `14px`                   | Chevron icon size                 |
+| `--stuic-tree-chevron-opacity`     | `0.5`                    | Chevron opacity                   |
+| `--stuic-tree-icon-opacity`        | `0.7`                    | Icon opacity                      |
+| `--stuic-tree-item-radius`         | `var(--stuic-radius)`    | Item border radius                |
+| `--stuic-tree-transition`          | `var(--stuic-transition)`| Transition duration               |
+
+### Colors
+
+| Variable                             | Default                                | Description               |
+| ------------------------------------ | -------------------------------------- | ------------------------- |
+| `--stuic-tree-item-bg`               | `transparent`                          | Item background           |
+| `--stuic-tree-item-text`             | `inherit`                              | Item text color           |
+| `--stuic-tree-item-bg-hover`         | `rgb(0 0 0 / 0.06)`                    | Hover background          |
+| `--stuic-tree-item-bg-focus`         | `rgb(0 0 0 / 0.06)`                    | Keyboard-focus background |
+| `--stuic-tree-item-bg-active`        | `var(--stuic-color-primary)`           | Active/selected bg        |
+| `--stuic-tree-item-text-active`      | `var(--stuic-color-primary-foreground)`| Active/selected text      |
+
+### Drag & drop
+
+| Variable                                | Default                            | Description                     |
+| --------------------------------------- | ---------------------------------- | ------------------------------- |
+| `--stuic-tree-item-opacity-dragging`    | `0.4`                              | Opacity of the dragged item     |
+| `--stuic-tree-drop-indicator-color`     | `var(--stuic-color-primary)`       | Before/after drop line color    |
+| `--stuic-tree-drop-indicator-height`    | `2px`                              | Before/after drop line height   |
+| `--stuic-tree-item-bg-dragover`         | `rgb(0 0 0 / 0.04)`                | "Inside"-drop highlight         |
+
+## Limitations
+
+- **No multi-select / checkbox selection.** Single active node only.
+- **No lazy loading.** All nodes must be present in `items`.
+- **Expansion state is private.** Observe via `onToggle`; set initial via `expandedIds`. There is currently no way to read the full set of expanded IDs from outside.
+- **Drag-drop is mouse-only.** See the a11y section above.