@spaethtech/svelte-ui 0.7.1-dev.41.d01009c → 0.7.1-dev.43.72e77ad

package/dist/components/SideBarMenu/SideBarMenu.svelte

@@ -4,7 +4,7 @@
  * bottom-anchored group (pushed to the strip's bottom edge), and hover-open
  * popouts for parent items.
  *
- * Driven by data — pass `topItems` / `bottomItems` arrays of {@link SideBarMenuItem}.
+ * Driven by data — pass `items` / `bottomItems` arrays of {@link SideBarMenuItem}.
  * Each item declares its own icon (Snippet), label, link, badge, and optional
  * children. Children render in a top-layer Popup on hover or click.
  *
@@ -33,6 +33,18 @@
    */
   export type SideBarMenuMode = "stepped" | "drawer" | "icon" | "expanded";
 
+  /** Imperative handle exposed via `bind:api`. */
+  export type SideBarMenuApi = {
+    /** Reset all transient state — close the drawer, clear the open popout, return step level to 0. */
+    reset: () => void;
+    /** Open the drawer (drawer/stepped modes). */
+    open: () => void;
+    /** Close the drawer. */
+    close: () => void;
+    /** Set the stepped-mode step level (`0` = top). */
+    setStepLevel: (n: number) => void;
+  };
+
   export type SideBarMenuBadgeVariant = "error" | "warning" | "info" | "success";
 
   export type SideBarMenuBadge = {
@@ -69,6 +81,15 @@
     badge?: SideBarMenuBadge;
     /** v1 renders only the first level; deeper levels emit a DEV warning. */
     children?: SideBarMenuItem[];
+    /** Action row (no `link`) — renders a `<button>` and calls this on click. For a "toggle"
+     *  row (an AI panel, etc.) or a non-navigating action. Runs after the drawer/popout reset. */
+    onclick?: (e: MouseEvent) => void;
+    /** Custom popout content, rendered INSTEAD of `children` in the popout (separators, hotkeys,
+     *  an account/identity block…). The row still needs an `icon`/`label`; this is just its popout. */
+    popout?: import("svelte").Snippet;
+    /** Opt this anchor out of client-side routing — stamps `data-sveltekit-reload` (SvelteKit) so
+     *  the link forces a full-browser navigation (sign-out endpoints, downloads, external redirects). */
+    reload?: boolean;
   };
 </script>
 
@@ -89,7 +110,7 @@
   type ModesMap = Partial<Record<Breakpoint, SideBarMenuMode>>;
 
   let {
-    topItems = [],
+    items = [],
     bottomItems = [],
     currentPath,
     size = "md",
@@ -100,9 +121,12 @@
     open = $bindable(false),
     stepLevel = $bindable(0),
     hamburger = true,
+    iconHoverExpand = false,
+    hoverExpandCloseMs = 200,
+    api = $bindable(),
     class: additionalClass = "",
   }: {
-    topItems?: SideBarMenuItem[];
+    items?: SideBarMenuItem[];
     bottomItems?: SideBarMenuItem[];
     currentPath: string;
     size?: Size;
@@ -149,6 +173,15 @@
      * and binds to `open`.
      */
     hamburger?: boolean;
+    /** In `icon` mode, expand the rail to `expanded` ON HOVER — as a floating overlay over a spacer
+     *  that reserves the collapsed width, so page content never reflows. Default `false`. */
+    iconHoverExpand?: boolean;
+    /** Exit delay (ms) before a hover-expanded rail collapses on mouse-leave. Default `200`. */
+    hoverExpandCloseMs?: number;
+    /** Imperative handle (bindable). Call `api.reset()` from your router's navigation lifecycle
+     *  (SvelteKit `afterNavigate`, etc.) so a programmatic `goto()`/back-button closes the drawer +
+     *  any open popout and returns a stepped drawer to the top. */
+    api?: SideBarMenuApi;
     class?: string;
   } = $props();
 
@@ -198,27 +231,55 @@
 
   const isStepped = $derived(currentMode === "stepped");
   const isDrawer = $derived(currentMode === "drawer" || currentMode === "stepped");
-  const labelsVisible = $derived(currentMode !== "icon");
+
+  // ── Icon-mode hover-expand ──────────────────────────────────────
+  // When enabled + in `icon` mode, hovering the rail floats it out to the `expanded` render OVER a
+  // spacer that reserves the collapsed width — page content never reflows. Exit is delayed.
+  let hoverExpanded = $state(false);
+  let hoverExpandTimer: ReturnType<typeof setTimeout> | null = null;
+  const hoverExpandActive = $derived(iconHoverExpand && currentMode === "icon");
+  const effectivelyExpanded = $derived(hoverExpandActive && hoverExpanded);
+  function openHoverExpand() {
+    if (hoverExpandTimer) {
+      clearTimeout(hoverExpandTimer);
+      hoverExpandTimer = null;
+    }
+    if (hoverExpandActive) hoverExpanded = true;
+  }
+  function scheduleHoverCollapse() {
+    if (hoverExpandTimer) clearTimeout(hoverExpandTimer);
+    hoverExpandTimer = setTimeout(() => {
+      hoverExpanded = false;
+      openId = null;
+      hoverExpandTimer = null;
+    }, hoverExpandCloseMs);
+  }
+  $effect(() => {
+    if (!hoverExpandActive) hoverExpanded = false;
+  });
+
+  // Labels show in every mode except a collapsed (not hover-expanded) icon rail.
+  const labelsVisible = $derived(currentMode !== "icon" || effectivelyExpanded);
 
   // ── DEV depth warning ───────────────────────────────────────────
   if (DEV) {
-    const walk = (items: SideBarMenuItem[], depth: number) => {
-      for (const it of items) {
+    const walk = (list: SideBarMenuItem[], depth: number, path: string[]) => {
+      for (const it of list) {
+        const here = [...path, it.label];
         if (it.children?.length) {
           if (depth >= 1) {
             console.warn(
-              'SideBarMenu: nesting deeper than 1 level is not yet rendered; flattening grandchildren of "' +
-                it.label +
-                '"',
+              `SideBarMenu: nesting deeper than 1 level is not yet rendered; flattening ` +
+                `grandchildren of "${here.join(" › ")}"`,
             );
             return;
           }
-          walk(it.children, depth + 1);
+          walk(it.children, depth + 1, here);
         }
       }
     };
-    walk(topItems, 0);
-    walk(bottomItems, 0);
+    walk(items, 0, []);
+    walk(bottomItems, 0, []);
   }
 
   // ── Size axis ───────────────────────────────────────────────────
@@ -327,6 +388,15 @@
     stepLevel = 1;
   }
 
+  // Imperative handle for consumers (bound via `bind:api`). Assigned once — the closures read the
+  // reactive `open`/`stepLevel`/`openId` live, so a single assignment stays correct.
+  api = {
+    reset: closeAfterNav,
+    open: () => (open = true),
+    close: () => (open = false),
+    setStepLevel: (n: number) => (stepLevel = n),
+  };
+
   // Label / chevron visibility are now driven by the active mode
   // instead of by responsive class strings — the matchMedia effect
   // above keeps `currentMode` (and therefore `labelsVisible`) in sync
@@ -503,27 +573,35 @@
 		     `chevronVisibility` (not `labelClassResolved`) so the span
 		     stays `inline-flex` and the SVG centers vertically. -->
     <span
-      class="shrink-0 items-center justify-center opacity-60 {sz.chevronBox} {sz.chevronSvg} {chevronClass}"
+      class="shrink-0 items-center justify-center opacity-60 transition-transform duration-150 {isOpen
+        ? 'rotate-180'
+        : ''} {sz.chevronBox} {sz.chevronSvg} {chevronClass}"
     >
       <IconChevronRight />
     </span>
   {/if}
 {/snippet}
 
-<!-- Single row template — used by topItems / bottomItems and the popout. -->
+<!-- Single row template — used by items / bottomItems and the popout. -->
 {#snippet row(item: SideBarMenuItem, opts: { id?: ItemId; isPopoutChild?: boolean })}
   {@const active = isItemActive(item)}
+  {@const ownActive = !!item.link && currentPath.startsWith(item.link)}
   {@const hasChildren = (item.children?.length ?? 0) > 0}
-  {@const isParent = hasChildren && !opts.isPopoutChild}
+  {@const isParent = (hasChildren || !!item.popout) && !opts.isPopoutChild}
   {@const hasLink = !!item.link}
   {@const isOpen = !!opts.id && openId === opts.id}
+  {@const popoutId = opts.id ? "sbm-popout-" + opts.id.replace(":", "-") : undefined}
   {@const rowClass = `group flex items-center w-full ${sz.row} lg:pr-3 transition-colors cursor-pointer ${active ? "[background-color:var(--ui-color-primary)] text-white" : isOpen ? "[background-color:color-mix(in_srgb,var(--ui-color-text)_10%,transparent)]" : "hover:[background-color:color-mix(in_srgb,var(--ui-color-text)_10%,transparent)]"}`}
   {#if hasLink}
     <a
       href={item.link}
       use:refIntoMap={opts.id}
       class={rowClass}
-      aria-current={active ? "page" : undefined}
+      data-sveltekit-reload={item.reload ? "" : undefined}
+      aria-current={ownActive ? "page" : undefined}
+      aria-haspopup={isParent ? "menu" : undefined}
+      aria-expanded={isParent && opts.id ? isOpen : undefined}
+      aria-controls={isParent && isOpen ? popoutId : undefined}
       use:tooltip={{
         text: item.label,
         side: "right",
@@ -562,6 +640,7 @@
       class="{rowClass} text-left"
       aria-haspopup="menu"
       aria-expanded={openId === opts.id}
+      aria-controls={isOpen ? popoutId : undefined}
       use:tooltip={{ text: item.label, side: "right", disabled: openId === opts.id }}
       onmouseenter={!isStepped ? () => openOnHover(opts.id!) : undefined}
       onmouseleave={!isStepped ? scheduleClose : undefined}
@@ -569,6 +648,21 @@
     >
       {@render rowBody(item, isParent, !!opts.isPopoutChild, isOpen)}
     </button>
+  {:else if item.onclick}
+    <!-- Action row: no link, no children/popout — a `<button>` that runs `onclick`
+         (e.g. an AI-panel toggle), then resets the drawer/popout like a leaf nav. -->
+    <button
+      type="button"
+      use:refIntoMap={opts.id}
+      class="{rowClass} text-left"
+      use:tooltip={{ text: item.label, side: "right" }}
+      onclick={(e) => {
+        item.onclick!(e);
+        closeAfterNav();
+      }}
+    >
+      {@render rowBody(item, false, !!opts.isPopoutChild, false)}
+    </button>
   {:else}
     <!-- Malformed item: no link, no children. Render visibly so the
 		     consumer notices, but with disabled-style cursor + opacity. -->
@@ -582,22 +676,27 @@
      mirrors main strip styling. `borderClass` is computed per popout
      by `geometryFor` so the visible edges get borders and the edges
      that coincide with the sidebar's top/bottom don't. -->
-{#snippet popout(item: SideBarMenuItem, borderClass: string)}
+{#snippet popout(item: SideBarMenuItem, borderClass: string, popoutId: string)}
   <!-- svelte-ignore a11y_interactive_supports_focus -->
   <div
     role="menu"
     tabindex="-1"
+    id={popoutId}
     class="w-[var(--sbm-expanded-w)] overflow-hidden shadow-lg [background-color:var(--ui-color-background)] [color:var(--ui-color-text)] [border-color:color-mix(in_srgb,var(--ui-color-text)_15%,transparent)] {borderClass}"
     onmouseenter={cancelClose}
     onmouseleave={scheduleClose}
   >
-    <ul class="flex flex-col">
-      {#each item.children ?? [] as child (child.label)}
-        <li class="list-none" role="none">
-          {@render row(child, { isPopoutChild: true })}
-        </li>
-      {/each}
-    </ul>
+    {#if item.popout}
+      {@render item.popout()}
+    {:else}
+      <ul class="flex flex-col">
+        {#each item.children ?? [] as child (child.label)}
+          <li class="list-none" role="none">
+            {@render row(child, { isPopoutChild: true })}
+          </li>
+        {/each}
+      </ul>
+    {/if}
   </div>
 {/snippet}
 
@@ -627,24 +726,34 @@
   ></div>
 {/if}
 
-<aside
-  bind:this={asideRef}
+<!-- Root wrapper. In icon hover-expand it becomes a `relative` spacer reserving the collapsed rail
+     width, so the expanded float below is positioned against the SIDEBAR's own box (container-relative,
+     never the viewport). In every other mode it's `display: contents` (no box) so layout is unchanged. -->
+<div
+  class={hoverExpandActive ? "relative shrink-0 [width:var(--sbm-collapsed-w)]" : "contents"}
   style="--sbm-collapsed-w: {collapsedWidth}px; --sbm-expanded-w: {expandedWidth}px;"
-  class="
+>
+  <aside
+    bind:this={asideRef}
+    onmouseenter={hoverExpandActive ? openHoverExpand : undefined}
+    onmouseleave={hoverExpandActive ? scheduleHoverCollapse : undefined}
+    class="
 		flex flex-col z-[60] overflow-hidden
 		[background-color:var(--ui-color-background)]
 		[color:var(--ui-color-text)]
 		[border-right:1px_solid_color-mix(in_srgb,var(--ui-color-text)_15%,transparent)]
 		{currentMode === 'stepped'
-    ? `absolute inset-y-0 left-0 w-full z-[75] transition-transform duration-200 ${open ? 'translate-x-0' : '-translate-x-full'}`
-    : currentMode === 'drawer'
-      ? `absolute inset-y-0 left-0 w-[var(--sbm-expanded-w)] z-[75] transition-transform duration-200 ${open ? 'translate-x-0' : '-translate-x-full'}`
-      : currentMode === 'icon'
-        ? 'relative w-[var(--sbm-collapsed-w)]'
-        : 'relative w-[var(--sbm-expanded-w)]'}
+      ? `absolute inset-y-0 left-0 w-full z-[75] transition-transform duration-200 ${open ? 'translate-x-0' : '-translate-x-full'}`
+      : currentMode === 'drawer'
+        ? `absolute inset-y-0 left-0 w-[var(--sbm-expanded-w)] z-[75] transition-transform duration-200 ${open ? 'translate-x-0' : '-translate-x-full'}`
+        : currentMode === 'icon'
+          ? hoverExpandActive
+            ? `absolute inset-y-0 left-0 z-[65] transition-[width] duration-200 ${effectivelyExpanded ? 'w-[var(--sbm-expanded-w)] shadow-lg' : 'w-[var(--sbm-collapsed-w)]'}`
+            : 'relative w-[var(--sbm-collapsed-w)]'
+          : 'relative w-[var(--sbm-expanded-w)]'}
 		{additionalClass}
 	"
->
+  >
   {#if isStepped && stepLevel === 1 && currentParent}
     <!-- Stepped sub-view (<2xs only): show just the children of the
 		     parent the user tapped. The consumer's hamburger button is
@@ -659,15 +768,15 @@
       {/each}
     </ul>
   {:else}
-    {#if topItems.length > 0}
+    {#if items.length > 0}
       <ul class="flex flex-col">
-        {#each topItems as item, idx (item.label)}
+        {#each items as item, idx (item.label)}
           {@const id = `top:${idx}` as ItemId}
           <li class="list-none">
             {@render row(item, { id })}
           </li>
-          {#if (item.children?.length ?? 0) > 0 && !isStepped}
-            {@const geom = geometryFor(id, "top", idx, topItems.length, item.children!.length)}
+          {#if ((item.children?.length ?? 0) > 0 || !!item.popout) && !isStepped}
+            {@const geom = geometryFor(id, "top", idx, items.length, item.children?.length ?? 1)}
             <Popup
               anchor={geom.anchor}
               open={openId === id}
@@ -678,14 +787,14 @@
                 if (openId === id) openId = null;
               }}
             >
-              {@render popout(item, geom.borderClass)}
+              {@render popout(item, geom.borderClass, "sbm-popout-" + id.replace(":", "-"))}
             </Popup>
           {/if}
         {/each}
       </ul>
     {/if}
 
-    {#if topItems.length > 0 && bottomItems.length > 0}
+    {#if items.length > 0 && bottomItems.length > 0}
       <div class="flex-1"></div>
     {/if}
 
@@ -696,13 +805,13 @@
           <li class="list-none">
             {@render row(item, { id })}
           </li>
-          {#if (item.children?.length ?? 0) > 0 && !isStepped}
+          {#if ((item.children?.length ?? 0) > 0 || !!item.popout) && !isStepped}
             {@const geom = geometryFor(
               id,
               "bottom",
               idx,
               bottomItems.length,
-              item.children!.length,
+              item.children?.length ?? 1,
             )}
             <Popup
               anchor={geom.anchor}
@@ -714,11 +823,12 @@
                 if (openId === id) openId = null;
               }}
             >
-              {@render popout(item, geom.borderClass)}
+              {@render popout(item, geom.borderClass, "sbm-popout-" + id.replace(":", "-"))}
             </Popup>
           {/if}
         {/each}
       </ul>
     {/if}
   {/if}
-</aside>
+  </aside>
+</div>

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

@@ -18,6 +18,17 @@
  *                 Designed for wide desktop.
  */
 export type SideBarMenuMode = "stepped" | "drawer" | "icon" | "expanded";
+/** Imperative handle exposed via `bind:api`. */
+export type SideBarMenuApi = {
+    /** Reset all transient state — close the drawer, clear the open popout, return step level to 0. */
+    reset: () => void;
+    /** Open the drawer (drawer/stepped modes). */
+    open: () => void;
+    /** Close the drawer. */
+    close: () => void;
+    /** Set the stepped-mode step level (`0` = top). */
+    setStepLevel: (n: number) => void;
+};
 export type SideBarMenuBadgeVariant = "error" | "warning" | "info" | "success";
 export type SideBarMenuBadge = {
     /** Color of the indicator. */
@@ -50,12 +61,21 @@ export type SideBarMenuItem = {
     badge?: SideBarMenuBadge;
     /** v1 renders only the first level; deeper levels emit a DEV warning. */
     children?: SideBarMenuItem[];
+    /** Action row (no `link`) — renders a `<button>` and calls this on click. For a "toggle"
+     *  row (an AI panel, etc.) or a non-navigating action. Runs after the drawer/popout reset. */
+    onclick?: (e: MouseEvent) => void;
+    /** Custom popout content, rendered INSTEAD of `children` in the popout (separators, hotkeys,
+     *  an account/identity block…). The row still needs an `icon`/`label`; this is just its popout. */
+    popout?: import("svelte").Snippet;
+    /** Opt this anchor out of client-side routing — stamps `data-sveltekit-reload` (SvelteKit) so
+     *  the link forces a full-browser navigation (sign-out endpoints, downloads, external redirects). */
+    reload?: boolean;
 };
 import type { Size } from "../../types/sizes.js";
 import { type Breakpoint } from "../../types/breakpoints.js";
 type ModesMap = Partial<Record<Breakpoint, SideBarMenuMode>>;
 type $$ComponentProps = {
-    topItems?: SideBarMenuItem[];
+    items?: SideBarMenuItem[];
     bottomItems?: SideBarMenuItem[];
     currentPath: string;
     size?: Size;
@@ -102,8 +122,17 @@ type $$ComponentProps = {
      * and binds to `open`.
      */
     hamburger?: boolean;
+    /** In `icon` mode, expand the rail to `expanded` ON HOVER — as a floating overlay over a spacer
+     *  that reserves the collapsed width, so page content never reflows. Default `false`. */
+    iconHoverExpand?: boolean;
+    /** Exit delay (ms) before a hover-expanded rail collapses on mouse-leave. Default `200`. */
+    hoverExpandCloseMs?: number;
+    /** Imperative handle (bindable). Call `api.reset()` from your router's navigation lifecycle
+     *  (SvelteKit `afterNavigate`, etc.) so a programmatic `goto()`/back-button closes the drawer +
+     *  any open popout and returns a stepped drawer to the top. */
+    api?: SideBarMenuApi;
     class?: string;
 };
-declare const SideBarMenu: import("svelte").Component<$$ComponentProps, {}, "open" | "stepLevel">;
+declare const SideBarMenu: import("svelte").Component<$$ComponentProps, {}, "open" | "stepLevel" | "api">;
 type SideBarMenu = ReturnType<typeof SideBarMenu>;
 export default SideBarMenu;

package/dist/index.d.ts

@@ -41,7 +41,7 @@ export type { Columns, Gap } from "./components/field-group.js";
 export { default as Disclosure } from "./components/Disclosure.svelte";
 export { default as Accordion } from "./components/Accordion.svelte";
 export { default as SideBarMenu } from "./components/SideBarMenu/SideBarMenu.svelte";
-export type { SideBarMenuItem, SideBarMenuBadge, SideBarMenuBadgeVariant, } from "./components/SideBarMenu/SideBarMenu.svelte";
+export type { SideBarMenuItem, SideBarMenuBadge, SideBarMenuBadgeVariant, SideBarMenuApi, } from "./components/SideBarMenu/SideBarMenu.svelte";
 export { default as TabStrip } from "./components/TabStrip/TabStrip.svelte";
 export type { TabDefinition } from "./components/TabStrip/TabStrip.svelte";
 export { default as DataTable } from "./components/DataTable.svelte";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaethtech/svelte-ui",
-  "version": "0.7.1-dev.41.d01009c",
+  "version": "0.7.1-dev.43.72e77ad",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/spaethtech/svelte-ui.git"