@spaethtech/svelte-ui 0.21.1-dev.127.89441ce → 0.21.1-dev.129.7debcd5

package/CLAUDE.md

@@ -162,9 +162,21 @@ host port). Get its IP with `docker inspect svelte-ui-demo-1 --format '{{range .
 (`svelte-ui-caddy-1` proxies to it; `php-svelte.spaethtech.dev` → the host `:5173`). `curl` the route
 first to confirm it serves, then point a browser at it.
 
+**For INTERACTION / HYDRATION testing, use the Caddy route `https://svelte-ui.spaethtech.dev/<route>`
+(Playwright `ignoreHTTPSErrors: true`), NOT the container IP.** Hitting the container IP `:5173`
+directly serves the SSR HTML but **intermittently fails to hydrate**: vite's HMR client tries
+`ws://<ip>:443` (refused) and the route's dynamic client module then fails to fetch, so the page stays
+SSR-only and **all client interactivity is dead** — clicks/keyboard/`bind:`/`oninput` do nothing, and a
+Svelte `.fill()` won't propagate to bound state. This looks exactly like a component bug but isn't; it
+bit this project's DatePicker2-reset and Tree-lazy verifications. The Caddy origin terminates TLS on
+`:443`, so HMR + module imports load and the page hydrates reliably. Container IP is fine for
+**SSR-only / visual** checks (screenshots of rendered markup); use Caddy whenever you click, type, or
+assert post-hydration state. Confirm hydration first (e.g. toggle a known control and see state flip)
+before trusting an interaction result — don't report "verified" from a page that never hydrated.
+
 Use the **`/playwright-cli`** workflow for browser-driven testing (navigation, snapshots/screenshots,
-console inspection, interaction). Point it at the **container IP** `:5173` and the relevant demo route
-(e.g. `/tabstrip`). The old Chrome DevTools MCP (`.mcp.json` + `chrome-devtools-mcp`) has been removed
+console inspection, interaction). Point it at the **Caddy route** for interaction (container IP only for
+SSR/visual) and the relevant demo route (e.g. `/tabstrip`). The old Chrome DevTools MCP (`.mcp.json` + `chrome-devtools-mcp`) has been removed
 in favor of this. **Browser-binary gotcha:** the Playwright in `node_modules` and the cached browser
 revision can mismatch (e.g. it wants `headless_shell-1181` but the cache has `chromium-1229`); pass
 `executablePath` to the installed `~/.cache/ms-playwright/chromium-*/chrome-linux64/chrome` instead of

package/dist/components/Tree/Tree.svelte

@@ -2,7 +2,9 @@
 /**
  * Tree — a hierarchical, expandable tree view (ARIA `tree`). Data-driven nodes; expand/collapse +
  * single-select with roving-tabindex keyboard nav (↑/↓ move, →/← expand/collapse, Enter/Space select).
- * Shared `variant`/`size` axes, `--ui-*` tokens. See Tree.spec.md.
+ * Shared `variant`/`size` axes, `--ui-*` tokens. Supports LAZY children (a `hasChildren` hint +
+ * `loadChildren`/`onexpand`), a per-node `oncontextmenu`/`data-key` for right-click menus, and
+ * `expandOnSelect={false}` to keep selection and expansion separate. See Tree.spec.md.
  */
 -->
 <script lang="ts" module>
@@ -14,22 +16,33 @@
     icon?: Snippet;
     children?: TreeNode[];
     disabled?: boolean;
+    /** Lazy-tree hint: `true` = has children (show the chevron) even before they're loaded; `false` =
+     *  definitely a leaf (no chevron); `undefined` = inferred from `children`. */
+    hasChildren?: boolean;
   };
 </script>
 
 <script lang="ts">
   import IconChevronRight from "~icons/mdi/chevron-right";
+  import IconLoading from "~icons/mdi/loading";
   import type { HTMLAttributes } from "svelte/elements";
   import type { Variant } from "../../types/variants.js";
   import { variantToken } from "../../types/variants.js";
   import type { Size } from "../../types/sizes.js";
   import { responsiveClasses, type Responsive } from "../../types/responsive.js";
+  import { uiI18n } from "../../i18n.js";
+
+  const i18n = uiI18n();
 
   let {
     items,
     expanded = $bindable([]),
     selected = $bindable(""),
     onselect,
+    onexpand,
+    oncontextmenu,
+    loadChildren,
+    expandOnSelect = true,
     variant = "primary",
     size = "md",
     class: cls = "",
@@ -41,12 +54,25 @@
     /** Key of the selected node (bindable). */
     selected?: string;
     onselect?: (node: TreeNode, key: string) => void;
+    /** Fired when a node is expanded — use with a consumer-managed `items` to load children yourself
+     *  (or use `loadChildren` to let the Tree own the fetch + spinner). */
+    onexpand?: (node: TreeNode, key: string) => void;
+    /** Right-click on a row. The event is NOT prevented, so a wrapping `ContextMenu` still opens;
+     *  each row also carries `data-key` for consumers that read the target instead. */
+    oncontextmenu?: (event: MouseEvent, node: TreeNode, key: string) => void;
+    /** Lazily load a node's children. Called once when an unloaded node (`hasChildren: true`, no
+     *  `children`) is first expanded: the Tree shows a spinner row, caches the resolved children, and
+     *  shows an inline error row on rejection. */
+    loadChildren?: (node: TreeNode, key: string) => Promise<TreeNode[]>;
+    /** `true` (default): selecting a parent also toggles it (current behaviour). `false`: select and
+     *  expand are separate — expand only via the chevron or →/←, as desktop explorers do. */
+    expandOnSelect?: boolean;
     variant?: Variant;
     size?: Responsive<Size>;
     class?: string;
-    // `style` omitted — rows compute their own inline style (indent + active tint). `onselect` omitted
-    // too: it collides with the DOM `onselect` in HTMLAttributes but has this component's own signature.
-  } & Omit<HTMLAttributes<HTMLElement>, "class" | "style" | "onselect"> = $props();
+    // `style`/`onselect`/`oncontextmenu` omitted from the DOM attrs: rows compute their own style, and
+    // the latter two have this component's own (node-aware) signatures.
+  } & Omit<HTMLAttributes<HTMLElement>, "class" | "style" | "onselect" | "oncontextmenu"> = $props();
 
   const token = $derived(variantToken[variant]);
   const rowH: Record<Size, string> = { sm: "h-7 text-xs", md: "h-8 text-sm", lg: "h-10 text-base" };
@@ -56,37 +82,95 @@
     lg: "[&_svg]:w-5 [&_svg]:h-5",
   };
 
-  type Flat = { key: string; node: TreeNode; level: number; hasChildren: boolean; open: boolean };
-  // Flattened list of VISIBLE nodes (children shown only under expanded parents) — drives rendering,
-  // roving tabindex, and arrow-key navigation.
+  // Lazily-loaded children + per-node load state, keyed by node key. Kept internal so `items` stays
+  // immutable for the consumer; `loadChildren`'s result is cached here and merged into the flat view.
+  let loadedChildren = $state<Record<string, TreeNode[]>>({});
+  let loadingKeys = $state<Record<string, boolean>>({});
+  let loadErrors = $state<Record<string, string>>({});
+
+  const childrenOf = (node: TreeNode, key: string): TreeNode[] | undefined =>
+    node.children ?? loadedChildren[key];
+  const nodeHasChildren = (node: TreeNode, key: string): boolean =>
+    node.hasChildren ?? (childrenOf(node, key)?.length ?? 0) > 0;
+
+  type Flat = {
+    key: string;
+    node: TreeNode;
+    level: number;
+    hasChildren: boolean;
+    open: boolean;
+    /** A synthetic, non-interactive row for a lazy node's load state. */
+    status?: "loading" | "error";
+    message?: string;
+  };
+  // Flattened list of VISIBLE rows (children shown only under expanded parents), plus synthetic
+  // loading/error rows for lazy nodes. Drives rendering; `navFlat` (real nodes only) drives keyboard nav.
   const flat = $derived.by<Flat[]>(() => {
     const out: Flat[] = [];
     const walk = (nodes: TreeNode[], level: number, prefix: string) => {
       nodes.forEach((node, i) => {
         const key = node.id ?? `${prefix}${i}`;
-        const hasChildren = !!node.children?.length;
+        const hasChildren = nodeHasChildren(node, key);
         const open = expanded.includes(key);
         out.push({ key, node, level, hasChildren, open });
-        if (hasChildren && open) walk(node.children!, level + 1, `${key}>`);
+        if (hasChildren && open) {
+          const kids = childrenOf(node, key);
+          if (kids && kids.length) walk(kids, level + 1, `${key}>`);
+          else if (loadingKeys[key])
+            out.push({ key: `${key}::loading`, node, level: level + 1, hasChildren: false, open: false, status: "loading" });
+          else if (loadErrors[key])
+            out.push({ key: `${key}::error`, node, level: level + 1, hasChildren: false, open: false, status: "error", message: loadErrors[key] });
+        }
       });
     };
     walk(items, 0, "");
     return out;
   });
+  const navFlat = $derived(flat.filter((f) => !f.status));
 
   let rowRefs = $state<Record<string, HTMLElement | undefined>>({});
   let activeKey = $state("");
   const tabKey = $derived(
-    flat.some((f) => f.key === activeKey) ? activeKey : (flat.find((f) => !f.node.disabled)?.key ?? ""),
+    navFlat.some((f) => f.key === activeKey)
+      ? activeKey
+      : (navFlat.find((f) => !f.node.disabled)?.key ?? ""),
   );
 
-  const toggle = (key: string) =>
-    (expanded = expanded.includes(key) ? expanded.filter((k) => k !== key) : [...expanded, key]);
+  function maybeLoad(f: Flat) {
+    if (!loadChildren) return;
+    const kids = childrenOf(f.node, f.key);
+    if ((kids && kids.length) || loadingKeys[f.key] || loadedChildren[f.key]) return;
+    loadingKeys = { ...loadingKeys, [f.key]: true };
+    const { [f.key]: _drop, ...restErrors } = loadErrors;
+    loadErrors = restErrors;
+    loadChildren(f.node, f.key)
+      .then((res) => {
+        loadedChildren = { ...loadedChildren, [f.key]: res };
+      })
+      .catch((err) => {
+        loadErrors = { ...loadErrors, [f.key]: err instanceof Error ? err.message : String(err) };
+      })
+      .finally(() => {
+        const { [f.key]: _done, ...restLoading } = loadingKeys;
+        loadingKeys = restLoading;
+      });
+  }
+
+  function setOpen(f: Flat, open: boolean) {
+    if (open === f.open) return;
+    expanded = open ? [...expanded, f.key] : expanded.filter((k) => k !== f.key);
+    if (open) {
+      onexpand?.(f.node, f.key);
+      maybeLoad(f);
+    }
+  }
+  const toggleOpen = (f: Flat) => setOpen(f, !f.open);
+
   function selectNode(f: Flat) {
     if (f.node.disabled) return;
     selected = f.key;
     onselect?.(f.node, f.key);
-    if (f.hasChildren) toggle(f.key);
+    if (f.hasChildren && expandOnSelect) toggleOpen(f);
   }
   const focusKey = (key: string) => {
     activeKey = key;
@@ -94,42 +178,42 @@
   };
 
   function onKeydown(e: KeyboardEvent) {
-    const idx = flat.findIndex((f) => f.key === tabKey);
+    const idx = navFlat.findIndex((f) => f.key === tabKey);
     if (idx < 0) return;
-    const f = flat[idx];
+    const f = navFlat[idx];
     switch (e.key) {
       case "ArrowDown":
         e.preventDefault();
-        if (idx < flat.length - 1) focusKey(flat[idx + 1].key);
+        if (idx < navFlat.length - 1) focusKey(navFlat[idx + 1].key);
         break;
       case "ArrowUp":
         e.preventDefault();
-        if (idx > 0) focusKey(flat[idx - 1].key);
+        if (idx > 0) focusKey(navFlat[idx - 1].key);
         break;
       case "ArrowRight":
         e.preventDefault();
-        if (f.hasChildren && !f.open) toggle(f.key);
-        else if (f.hasChildren && flat[idx + 1]) focusKey(flat[idx + 1].key);
+        if (f.hasChildren && !f.open) setOpen(f, true);
+        else if (f.hasChildren && navFlat[idx + 1]) focusKey(navFlat[idx + 1].key);
         break;
       case "ArrowLeft":
         e.preventDefault();
-        if (f.hasChildren && f.open) toggle(f.key);
+        if (f.hasChildren && f.open) setOpen(f, false);
         else {
           // move to parent (previous node at a lower level)
           for (let j = idx - 1; j >= 0; j--)
-            if (flat[j].level < f.level) {
-              focusKey(flat[j].key);
+            if (navFlat[j].level < f.level) {
+              focusKey(navFlat[j].key);
               break;
             }
         }
         break;
       case "Home":
         e.preventDefault();
-        focusKey(flat[0].key);
+        focusKey(navFlat[0].key);
         break;
       case "End":
         e.preventDefault();
-        focusKey(flat[flat.length - 1].key);
+        focusKey(navFlat[navFlat.length - 1].key);
         break;
       case "Enter":
       case " ":
@@ -148,40 +232,71 @@
   onkeydown={onKeydown}
 >
   {#each flat as f (f.key)}
-    {@const active = selected === f.key}
-    <li role="none" class="list-none">
-      <!-- svelte-ignore a11y_click_events_have_key_events -->
-      <div
-        bind:this={rowRefs[f.key]}
-        role="treeitem"
-        aria-level={f.level + 1}
-        aria-selected={active}
-        aria-expanded={f.hasChildren ? f.open : undefined}
-        aria-disabled={f.node.disabled || undefined}
-        tabindex={f.key === tabKey ? 0 : -1}
-        onclick={() => selectNode(f)}
-        onfocus={() => (activeKey = f.key)}
-        style="padding-inline-start: {f.level * 1.25 + 0.5}rem; {active
-          ? `background-color: color-mix(in srgb, var(${token}) 16%, transparent);`
-          : ''}"
-        class="group flex items-center gap-1.5 rounded-[var(--ui-border-radius)] pr-2 transition-colors {responsiveClasses(
-          size,
-          rowH,
-        )} {f.node.disabled
-          ? 'opacity-50 cursor-not-allowed'
-          : 'cursor-pointer hover:[background-color:var(--ui-color-hover)]'} focus-visible:[outline:2px_solid_color-mix(in_srgb,var(--ui-color-text)_70%,transparent)] focus-visible:[outline-offset:-2px]"
-      >
-        {#if f.hasChildren}
-          <span
-            class="inline-flex shrink-0 items-center justify-center transition-transform duration-150 {f.open
-              ? 'rotate-90'
-              : ''}"><IconChevronRight /></span>
-        {:else}
+    {#if f.status}
+      <!-- Synthetic lazy-load status row (non-interactive). -->
+      <li role="none" class="list-none">
+        <div
+          class="flex items-center gap-1.5 pr-2 {responsiveClasses(size, rowH)} [color:color-mix(in_srgb,var(--ui-color-text)_60%,transparent)]"
+          style="padding-inline-start: {f.level * 1.25 + 0.5}rem;"
+        >
           <span class="inline-block w-4 shrink-0"></span>
-        {/if}
-        {#if f.node.icon}<span class="inline-flex shrink-0">{@render f.node.icon()}</span>{/if}
-        <span class="truncate [color:var(--ui-color-text)]">{f.node.label}</span>
-      </div>
-    </li>
+          {#if f.status === "loading"}
+            <span class="inline-flex shrink-0 animate-spin"><IconLoading /></span>
+            <span class="truncate">{i18n.messages.loading}</span>
+          {:else}
+            <span class="truncate [color:var(--ui-color-error)]">{f.message || i18n.messages.loadFailed}</span>
+          {/if}
+        </div>
+      </li>
+    {:else}
+      {@const active = selected === f.key}
+      <li role="none" class="list-none">
+        <!-- svelte-ignore a11y_click_events_have_key_events -->
+        <div
+          bind:this={rowRefs[f.key]}
+          role="treeitem"
+          data-key={f.key}
+          aria-level={f.level + 1}
+          aria-selected={active}
+          aria-expanded={f.hasChildren ? f.open : undefined}
+          aria-disabled={f.node.disabled || undefined}
+          tabindex={f.key === tabKey ? 0 : -1}
+          onclick={() => selectNode(f)}
+          oncontextmenu={(e) => oncontextmenu?.(e, f.node, f.key)}
+          onfocus={() => (activeKey = f.key)}
+          style="padding-inline-start: {f.level * 1.25 + 0.5}rem; {active
+            ? `background-color: color-mix(in srgb, var(${token}) 16%, transparent);`
+            : ''}"
+          class="group flex items-center gap-1.5 rounded-[var(--ui-border-radius)] pr-2 transition-colors {responsiveClasses(
+            size,
+            rowH,
+          )} {f.node.disabled
+            ? 'opacity-50 cursor-not-allowed'
+            : 'cursor-pointer hover:[background-color:var(--ui-color-hover)]'} focus-visible:[outline:2px_solid_color-mix(in_srgb,var(--ui-color-text)_70%,transparent)] focus-visible:[outline-offset:-2px]"
+        >
+          {#if f.hasChildren && !expandOnSelect}
+            <!-- Select and expand are separate: the chevron is its own control (keyboard expand is
+                 still →/←). A real <button> keeps it accessible without a roving tab stop. -->
+            <button
+              type="button"
+              tabindex="-1"
+              aria-label={f.open ? i18n.messages.collapse : i18n.messages.expand}
+              class="inline-flex shrink-0 cursor-pointer items-center justify-center rounded transition-transform duration-150 {f.open
+                ? 'rotate-90'
+                : ''}"
+              onclick={(e) => (e.stopPropagation(), toggleOpen(f))}><IconChevronRight /></button>
+          {:else if f.hasChildren}
+            <span
+              class="inline-flex shrink-0 items-center justify-center transition-transform duration-150 {f.open
+                ? 'rotate-90'
+                : ''}"><IconChevronRight /></span>
+          {:else}
+            <span class="inline-block w-4 shrink-0"></span>
+          {/if}
+          {#if f.node.icon}<span class="inline-flex shrink-0">{@render f.node.icon()}</span>{/if}
+          <span class="truncate [color:var(--ui-color-text)]">{f.node.label}</span>
+        </div>
+      </li>
+    {/if}
   {/each}
 </ul>

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

@@ -6,6 +6,9 @@ export type TreeNode = {
     icon?: Snippet;
     children?: TreeNode[];
     disabled?: boolean;
+    /** Lazy-tree hint: `true` = has children (show the chevron) even before they're loaded; `false` =
+     *  definitely a leaf (no chevron); `undefined` = inferred from `children`. */
+    hasChildren?: boolean;
 };
 import type { HTMLAttributes } from "svelte/elements";
 import type { Variant } from "../../types/variants.js";
@@ -18,10 +21,23 @@ type $$ComponentProps = {
     /** Key of the selected node (bindable). */
     selected?: string;
     onselect?: (node: TreeNode, key: string) => void;
+    /** Fired when a node is expanded — use with a consumer-managed `items` to load children yourself
+     *  (or use `loadChildren` to let the Tree own the fetch + spinner). */
+    onexpand?: (node: TreeNode, key: string) => void;
+    /** Right-click on a row. The event is NOT prevented, so a wrapping `ContextMenu` still opens;
+     *  each row also carries `data-key` for consumers that read the target instead. */
+    oncontextmenu?: (event: MouseEvent, node: TreeNode, key: string) => void;
+    /** Lazily load a node's children. Called once when an unloaded node (`hasChildren: true`, no
+     *  `children`) is first expanded: the Tree shows a spinner row, caches the resolved children, and
+     *  shows an inline error row on rejection. */
+    loadChildren?: (node: TreeNode, key: string) => Promise<TreeNode[]>;
+    /** `true` (default): selecting a parent also toggles it (current behaviour). `false`: select and
+     *  expand are separate — expand only via the chevron or →/←, as desktop explorers do. */
+    expandOnSelect?: boolean;
     variant?: Variant;
     size?: Responsive<Size>;
     class?: string;
-} & Omit<HTMLAttributes<HTMLElement>, "class" | "style" | "onselect">;
+} & Omit<HTMLAttributes<HTMLElement>, "class" | "style" | "onselect" | "oncontextmenu">;
 declare const Tree: import("svelte").Component<$$ComponentProps, {}, "selected" | "expanded">;
 type Tree = ReturnType<typeof Tree>;
 export default Tree;

package/dist/i18n.d.ts

@@ -25,6 +25,9 @@ export type UiMessages = {
     next: Msg;
     first: Msg;
     last: Msg;
+    /** Tree: the per-row chevron toggle (accessible name), when select and expand are separate. */
+    expand: Msg;
+    collapse: Msg;
     pagination: Msg;
     pageNumber: Msg;
     perPage: Msg;

package/dist/i18n.js

@@ -23,6 +23,8 @@ export const defaultUiMessages = {
     next: "Next",
     first: "First",
     last: "Last",
+    expand: "Expand",
+    collapse: "Collapse",
     pagination: "Pagination",
     pageNumber: "Page number",
     perPage: "per page",

package/docs/components.md

@@ -850,8 +850,17 @@ Hierarchical, expandable tree view (ARIA `tree`).
 
 - **Location**: `src/lib/components/Tree/Tree.svelte`
 - **Axes**: `variant` (selected-row tint), `size`
-- **Props**: `items` (`TreeNode[]` = `{ label, id?, icon?, children?, disabled? }`), `expanded`
-  (bindable `string[]`), `selected` (bindable key), `onselect`, `class`
+- **Props**: `items` (`TreeNode[]` = `{ label, id?, icon?, children?, disabled?, hasChildren? }`),
+  `expanded` (bindable `string[]`), `selected` (bindable key), `onselect`, `class`
+- **Lazy children**: set `hasChildren: true` on a node whose `children` aren't loaded (it gets a
+  chevron). Provide **`loadChildren(node, key) => Promise<TreeNode[]>`** — it's called once on first
+  expand; the Tree shows a spinner row, caches the result (so `items` stays immutable), and shows an
+  inline error row (the rejection's message, else localized `loadFailed`) on failure. Or use
+  **`onexpand(node, key)`** to load into your own `items`.
+- **Right-click**: **`oncontextmenu(event, node, key)`** per row (the event isn't prevented, so a
+  wrapping `ContextMenu` still opens); every `role="treeitem"` also carries **`data-key`**.
+- **Select vs. expand**: **`expandOnSelect`** (default `true`) — set `false` so a row click only
+  selects and expansion is via the chevron (a real `<button>`) or →/←, as desktop explorers do.
 - **Keyboard**: roving tabindex — ↑/↓ move, → expand/into child, ← collapse/to parent, Enter/Space
   select, Home/End
 - **Accessibility**: `role="tree"`/`treeitem` with `aria-level`/`-expanded`/`-selected`/`-disabled`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaethtech/svelte-ui",
-  "version": "0.21.1-dev.127.89441ce",
+  "version": "0.21.1-dev.129.7debcd5",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/spaethtech/svelte-ui.git"