@spaethtech/svelte-ui 0.9.0 → 0.10.0

package/.claude/skills/svelte-ui/SKILL.md

@@ -166,7 +166,12 @@ examples):
   · `Popup` `Menu` · `tooltip` (a Svelte `use:` action) · `anchored` (positioning engine)
 - **Navigation:** `TabStrip` (tabs; `size`/`variant`, `gap`/`pad` bordered spacer cells, `height` for a
   fixed-height bar with bottom-aligned tabs, `activeSurface` to flow the active tab into the content
-  below) · `SideBarMenu`
+  below) · **`SideBarMenu`** (data-driven vertical nav: `items`/`bottomItems` of `SideBarMenuItem`
+  {`icon`,`label`,`link`,`badge`,`children`,`onclick`,`popout`,`reload`,`trailing` snippet,`activeMatch`};
+  responsive `modes` map + `iconHoverExpand`; `variant` tints only hover/active; `size`; `side`;
+  `interactMode` `'hover'|'click'` popouts; `currentPath` active-match (per-item `activeMatch` for
+  query-keyed/exact rules); `bind:open`/`bind:api`/`bind:activeMode`; `publishWidthVar` → CSS width var;
+  popouts expose `data-sbm-popout`/`data-open`)
 - **Feedback:** `Alert` `Banner` `Badge` `Toaster` + `toast`
 - **Layout:** `Card` `CardHeader` `CardBody` `CardFooter` · **`Grid`** (auto-placed equal-cell grid;
   `columns` + `gap`)

package/dist/components/Popup.svelte

@@ -41,6 +41,7 @@
     variant,
     size = "md",
     borderless = false,
+    lightDismiss = true,
     onclose,
     children,
   }: {
@@ -66,6 +67,10 @@
     size?: Responsive<Size>;
     /** Drop the panel's visible border (border = its own background). */
     borderless?: boolean;
+    /** Built-in dismiss on outside pointerdown / Escape. Default `true`. Set `false` when the owner
+     *  manages dismissal itself — e.g. a cascade of nested popouts, where each popout is "outside" its
+     *  parent's top-layer element and would otherwise close its ancestors. */
+    lightDismiss?: boolean;
     onclose?: () => void;
     children: Snippet;
   } = $props();
@@ -101,9 +106,9 @@
     else if (!open && isOpen) el.hidePopover();
   });
 
-  // Dismiss on Escape / outside pointerdown while open.
+  // Dismiss on Escape / outside pointerdown while open (unless the owner opts out via `lightDismiss`).
   $effect(() => {
-    if (!open) return;
+    if (!open || !lightDismiss) return;
     const onKey = (e: KeyboardEvent) => {
       if (e.key === "Escape") {
         e.preventDefault();
@@ -127,6 +132,7 @@
 <div
   bind:this={el}
   popover="manual"
+  data-open={open}
   class="m-0 overflow-visible {surfaceClass}"
   style={surface ? `border-color: ${panelBorder};` : ""}
   use:anchored={{

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

@@ -26,6 +26,10 @@ type $$ComponentProps = {
     size?: Responsive<Size>;
     /** Drop the panel's visible border (border = its own background). */
     borderless?: boolean;
+    /** Built-in dismiss on outside pointerdown / Escape. Default `true`. Set `false` when the owner
+     *  manages dismissal itself — e.g. a cascade of nested popouts, where each popout is "outside" its
+     *  parent's top-layer element and would otherwise close its ancestors. */
+    lightDismiss?: boolean;
     onclose?: () => void;
     children: Snippet;
 };

package/dist/components/SideBarMenu/SideBarMenu.svelte

@@ -68,6 +68,21 @@
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   export type SideBarMenuItemIcon = any;
 
+  /**
+   * How an item decides it's "active" against `currentPath`. Absent → the default
+   * `currentPath` matches `link` on a segment boundary.
+   *  - `string` / `string[]` — path prefix(es) (segment-boundary match, like `link`).
+   *  - object — `path` prefix(es) PLUS optional `query` params that must ALL match (compared against
+   *    `currentPath`'s query string, so pass `pathname + search` as `currentPath`), and `exact` to
+   *    require the path to equal rather than prefix-match. Other query params are ignored.
+   * Use it for cross-group items keyed by a query param (e.g. `?via=network`) so a module that appears
+   * in several groups only highlights in the right one.
+   */
+  export type SideBarMenuActiveRule =
+    | string
+    | string[]
+    | { path: string | string[]; query?: Record<string, string>; exact?: boolean };
+
   export type SideBarMenuItem = {
     /**
      * Icon component constructor — same idiom as `MenuItem.icon`. Pass an
@@ -79,7 +94,8 @@
     /** href; absent when the item is a parent that only hosts children. */
     link?: string;
     badge?: SideBarMenuBadge;
-    /** v1 renders only the first level; deeper levels emit a DEV warning. */
+    /** Child items — rendered as a fly-out popout. Recursive: a child that itself has children
+     *  cascades into a further popout (or steps deeper in `stepped` mode). */
     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. */
@@ -90,11 +106,17 @@
     /** 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;
+    /** Trailing-slot content rendered on the row's far end (after the label, before the parent chevron
+     *  if any) — a state indicator, a dock/mute/notify glyph, a count, etc. Shown wherever the label is.
+     *  Sized/positioned like the chevron; mirrors to the other edge under `side="right"`. */
+    trailing?: import("svelte").Snippet;
+    /** Override how this item computes its active state (see {@link SideBarMenuActiveRule}). Absent →
+     *  the default `currentPath` segment-boundary match against `link`. */
+    activeMatch?: SideBarMenuActiveRule;
   };
 </script>
 
 <script lang="ts">
-  import { DEV } from "esm-env";
   import Popup from "../Popup.svelte";
   import { tooltip } from "../../positioning/tooltip.js";
   import IconAlert from "~icons/mdi/alert";
@@ -129,6 +151,7 @@
     side = "left",
     api = $bindable(),
     activeMode = $bindable(),
+    publishWidthVar,
     class: additionalClass = "",
   }: {
     items?: SideBarMenuItem[];
@@ -175,10 +198,10 @@
      */
     open?: boolean;
     /**
-     * Step-navigation level inside the `stepped`-mode drawer.
-     * `0` = top-level. `1` = inside a parent item's children list.
-     * Bind from the consumer so a header button can read it (e.g.
-     * to flip X → ← icon) and write it (set to `0` to navigate back).
+     * Step-navigation DEPTH inside the `stepped`-mode drawer (breadcrumb length).
+     * `0` = top-level, `1` = inside a parent's children, `2` = a grandparent's, … Bind from the
+     * consumer so a header button can read it (e.g. flip X → ← when `> 0`) and write it to go BACK
+     * one level (`stepLevel - 1`), or `0` to return to the top.
      */
     stepLevel?: number;
     /**
@@ -212,9 +235,20 @@
     /** Read-only (bindable) — the currently active {@link SideBarMenuMode}. Bind it to decide whether
      *  your own header trigger should render (e.g. only in `drawer`/`stepped`). */
     activeMode?: SideBarMenuMode;
+    /** Publish the strip's live pixel width to a CSS custom property on `:root` (kept current via a
+     *  `ResizeObserver`), so sibling layout can offset by it without its own observer. `true` →
+     *  `--sbm-current-width`; a string → that custom-property name (use a distinct name per instance
+     *  when you run more than one). Unset → nothing published. */
+    publishWidthVar?: boolean | string;
     class?: string;
   } = $props();
 
+  // Per-instance, hydration-stable id prefix so popout DOM ids are unique when more than one
+  // SideBarMenu renders on a page (otherwise `sbm-popout-top-1` collides, breaking `aria-controls`
+  // and `getElementById`). `$props.id()` is consistent across SSR + client.
+  const uid = $props.id();
+  const popoutDomId = (id: ItemId) => `${uid}-sbm-popout-${id.replace(/[:>]/g, "-")}`;
+
   // Default mode map — replicates the pre-modes behavior so old
   // consumers continue working unchanged. `collapsedAt` plugs into the
   // `expanded` slot so the legacy prop still tunes where labels appear.
@@ -246,7 +280,13 @@
   // the server `window` is undefined, so SSR emits `expanded`; the client corrects during hydration
   // (not via a delayed effect). The effect below keeps it in sync on subsequent viewport changes.
   let currentMode = $state<SideBarMenuMode>(
-    typeof window !== "undefined" ? resolveMode(effectiveModes, window.innerWidth) : "expanded",
+    typeof window !== "undefined"
+      ? resolveMode(effectiveModes, window.innerWidth)
+      : // SSR has no viewport. Resolve at the WIDEST width: a forced/single-mode map (e.g.
+        // `{ base: "icon" }`) then resolves EXACTLY, so a forced icon rail renders collapsed on the
+        // server and doesn't flash from `expanded` → `icon` on hydration. A responsive map still
+        // resolves to its top tier (typically `expanded`) — SSR can't know the real viewport.
+        resolveMode(effectiveModes, Number.MAX_SAFE_INTEGER),
   );
 
   $effect(() => {
@@ -375,27 +415,6 @@
           : "",
   );
 
-  // ── DEV depth warning ───────────────────────────────────────────
-  if (DEV) {
-    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 "${here.join(" › ")}"`,
-            );
-            return;
-          }
-          walk(it.children, depth + 1, here);
-        }
-      }
-    };
-    walk(items, 0, []);
-    walk(bottomItems, 0, []);
-  }
-
   // ── Size axis ───────────────────────────────────────────────────
   // All sub-element sizes derive from the icon size:
   //   - Badge icon  ≈ icon × 0.5  (warning/error/info/success glyph)
@@ -413,8 +432,8 @@
     pill: string; // min-w + h literal for the count pill
     pillText: string; // text-[Npx] for the count digits
     pillOffset: string; // absolute top-[N] right-[N] for the count pill
-    chevronBox: string; // wrapper around the parent-row chevron
-    chevronSvg: string; // chevron SVG sizing
+    chevronBox: string; // chevron/trailing wrapper — sized to the GLYPH (no dead space) so the 1rem
+    chevronSvg: string; // gap lands on the visible chevron, not an oversized box
   };
   const sizeMap: Record<Size, SizeStyles> = {
     sm: {
@@ -430,7 +449,7 @@
       pill: "min-w-[12px] h-[12px]",
       pillText: "text-[8px]",
       pillOffset: "top-[4px] right-[4px]",
-      chevronBox: "w-5 h-5",
+      chevronBox: "w-3.5 h-3.5",
       chevronSvg: "[&_svg]:w-3.5 [&_svg]:h-3.5",
     },
     md: {
@@ -443,7 +462,7 @@
       pill: "min-w-[14px] h-[14px]",
       pillText: "text-[9px]",
       pillOffset: "top-[5px] right-[5px]",
-      chevronBox: "w-6 h-6",
+      chevronBox: "w-4 h-4",
       chevronSvg: "[&_svg]:w-4 [&_svg]:h-4",
     },
     lg: {
@@ -456,12 +475,20 @@
       pill: "min-w-[16px] h-[16px]",
       pillText: "text-[10px]",
       pillOffset: "top-[6px] right-[6px]",
-      chevronBox: "w-7 h-7",
+      chevronBox: "w-5 h-5",
       chevronSvg: "[&_svg]:w-5 [&_svg]:h-5",
     },
   };
   const sz = $derived(sizeMap[size]);
 
+  // A group reserves the leading icon column only when at least one of its items has an icon (or a
+  // badge, which is anchored to the icon box). A group with none → labels aren't indented. Items in a
+  // reserving group that lack an icon still get an empty box so everything aligns. The main rail counts
+  // `items` + `bottomItems` as ONE group (so top/bottom align); each popout / stepped sub-view is its
+  // own group.
+  const anyIcon = (list: SideBarMenuItem[]) => list.some((i) => i.icon || i.badge);
+  const railReserve = $derived(anyIcon(items) || anyIcon(bottomItems));
+
   // ── Mobile drawer state ─────────────────────────────────────────
   // Below `xs` the strip collapses to `width: 0` and either the built-in
   // hamburger (default) or a consumer-provided trigger toggles a slide-in
@@ -482,24 +509,26 @@
     openId = null;
   }
 
-  // The parent whose children the drawer is currently displaying (when
-  // `stepLevel === 1`). Reset to null whenever stepLevel returns to 0
-  // or the drawer closes — the next step starts fresh from the top.
-  let currentParent = $state<SideBarMenuItem | null>(null);
+  // Breadcrumb of parents the stepped drawer has descended into. `stepLevel` mirrors its length:
+  // 0 = top, 1 = inside a parent, 2 = a grandparent, … The drawer shows the LAST entry's children.
+  let stepPath = $state<SideBarMenuItem[]>([]);
 
+  // Keep the (bindable) `stepLevel` and the internal path in sync: when the consumer decreases
+  // `stepLevel` (a "back" affordance, or 0) truncate the path to match.
   $effect(() => {
-    if (stepLevel === 0) currentParent = null;
+    if (stepLevel < stepPath.length) stepPath = stepPath.slice(0, stepLevel);
   });
   $effect(() => {
     if (!open) {
       stepLevel = 0;
-      currentParent = null;
+      stepPath = [];
     }
   });
 
-  function stepIntoChildren(item: SideBarMenuItem) {
-    currentParent = item;
-    stepLevel = 1;
+  function stepIntoChildren(item: SideBarMenuItem, _id?: ItemId) {
+    const next = [...stepPath, item];
+    stepPath = next;
+    stepLevel = next.length;
   }
 
   // Imperative handle for consumers (bound via `bind:api`). Assigned once — the closures read the
@@ -542,19 +571,65 @@
     if (link === "/") return false;
     return path.startsWith(link.endsWith("/") ? link : link + "/");
   }
+
+  // `currentPath` split into path + query, so `activeMatch` rules can test query params. Only the
+  // path portion is used for prefix matching; the params are consulted for `query` rules.
+  const parsedCurrent = $derived.by(() => {
+    const q = currentPath.indexOf("?");
+    return q === -1
+      ? { path: currentPath, params: new URLSearchParams() }
+      : { path: currentPath.slice(0, q), params: new URLSearchParams(currentPath.slice(q + 1)) };
+  });
+
+  function matchesActive(rule: SideBarMenuActiveRule): boolean {
+    const { path: curPath, params } = parsedCurrent;
+    const obj = typeof rule === "object" && !Array.isArray(rule);
+    const paths = typeof rule === "string" ? [rule] : Array.isArray(rule) ? rule : [rule.path].flat();
+    const exact = obj ? !!rule.exact : false;
+    if (!paths.some((p) => (exact ? p === curPath : pathMatches(p, curPath)))) return false;
+    if (obj && rule.query) {
+      for (const [k, v] of Object.entries(rule.query)) if (params.get(k) !== v) return false;
+    }
+    return true;
+  }
+
+  // Active when `activeMatch` matches (if provided), else the default segment-boundary match on `link`.
+  // A parent is also active when any descendant matches. `activeMatch` fully replaces the link default
+  // for that item (opt-in — the default behaviour is unchanged for items without it).
   function isItemActive(item: SideBarMenuItem): boolean {
-    if (item.link && pathMatches(item.link, currentPath)) return true;
+    if (item.activeMatch !== undefined) {
+      if (matchesActive(item.activeMatch)) return true;
+    } else if (item.link && pathMatches(item.link, currentPath)) {
+      return true;
+    }
     if (item.children?.length) return item.children.some(isItemActive);
     return false;
   }
+  // A row's OWN active state (drives `aria-current`) — its own rule/link only, never descendants.
+  function isItemOwnActive(item: SideBarMenuItem): boolean {
+    return item.activeMatch !== undefined
+      ? matchesActive(item.activeMatch)
+      : !!item.link && pathMatches(item.link, currentPath);
+  }
 
   // ── Hover/click open state ──────────────────────────────────────
-  type ItemId = `top:${number}` | `bottom:${number}`;
+  // An id is a group-prefixed INDEX PATH: `top:0`, `top:0>2`, `bottom:1>0>3` (">" separates tiers).
+  // `openId` holds the DEEPEST open node; a popout is open when its node is on that path (itself or an
+  // ancestor), so a whole cascade of fly-outs can be open at once.
+  type ItemId = string;
 
   let openId = $state<ItemId | null>(null);
   let closeTimer: ReturnType<typeof setTimeout> | null = null;
   const CLOSE_GRACE_MS = 150;
 
+  // The parent path of an id (drop the last tier); `null` at the top level (→ close everything).
+  const parentOf = (id: ItemId): ItemId | null => {
+    const i = id.lastIndexOf(">");
+    return i === -1 ? null : id.slice(0, i);
+  };
+  // Is this node's popout open? True when it IS the deepest open node or an ANCESTOR of it.
+  const isOnPath = (id: ItemId): boolean => openId === id || (openId?.startsWith(id + ">") ?? false);
+
   function cancelClose() {
     if (closeTimer !== null) {
       clearTimeout(closeTimer);
@@ -568,13 +643,17 @@
       closeTimer = null;
     }, CLOSE_GRACE_MS);
   }
-  function openOnHover(id: ItemId) {
+  // Hovering a row sets the open path: a PARENT opens its own popout (ancestors stay open, siblings +
+  // their sub-trees close); a LEAF drops to its parent path (keeps the branch it's in, closes deeper).
+  function openOnHover(id: ItemId, isParent: boolean) {
     cancelClose();
-    if (openId !== id) openId = id;
+    const target = isParent ? id : parentOf(id);
+    if (openId !== target) openId = target;
   }
+  // Click toggles this node's popout: open it, or if it's already the deepest, collapse to its parent.
   function toggleOnClick(id: ItemId) {
     cancelClose();
-    openId = openId === id ? null : id;
+    openId = openId === id ? parentOf(id) : id;
   }
 
   // ── Refs ────────────────────────────────────────────────────────
@@ -582,6 +661,50 @@
   // One ref per parent trigger. Keyed by ItemId so Popup can anchor.
   const triggerRefs = $state<Record<string, HTMLElement | undefined>>({});
 
+  // ── Cascade dismiss ─────────────────────────────────────────────
+  // The popouts run with `lightDismiss={false}` (a nested popout is "outside" its parent's top-layer
+  // element, so per-popout dismiss would close ancestors). Manage it here for the whole chain: an
+  // outside pointerdown closes everything; Escape steps up one level.
+  $effect(() => {
+    const onDown = (e: PointerEvent) => {
+      if (openId === null) return;
+      const t = e.target as Node | null;
+      if (asideRef?.contains(t)) return;
+      if (t instanceof Element && t.closest("[data-sbm-popout]")) return;
+      openId = null;
+    };
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== "Escape" || openId === null) return;
+      e.preventDefault();
+      openId = null; // close the whole cascade (one-level-close fights a still-hovering pointer)
+    };
+    document.addEventListener("pointerdown", onDown, true);
+    document.addEventListener("keydown", onKey, true);
+    return () => {
+      document.removeEventListener("pointerdown", onDown, true);
+      document.removeEventListener("keydown", onKey, true);
+    };
+  });
+
+  // ── Publish width (opt-in) ──────────────────────────────────────
+  // When `publishWidthVar` is set, mirror the strip's live width to a CSS var on `:root` so sibling
+  // layout can react to it (icon rail ⇄ expanded, hover-expand float, drawer slide) without its own
+  // ResizeObserver. Cleaned up (and the var removed) when disabled or the component unmounts.
+  $effect(() => {
+    if (!publishWidthVar || !asideRef) return;
+    const name = typeof publishWidthVar === "string" ? publishWidthVar : "--sbm-current-width";
+    const root = document.documentElement;
+    const node = asideRef;
+    const write = () => root.style.setProperty(name, `${node.offsetWidth}px`);
+    write();
+    const ro = new ResizeObserver(write);
+    ro.observe(node);
+    return () => {
+      ro.disconnect();
+      root.style.removeProperty(name);
+    };
+  });
+
   // Callback-ref action — `bind:this` can't take a {get, set} pair and can't
   // take a ternary expression, so we use a tiny action to wire each row's
   // DOM node into the triggerRefs map by id. No-op when id is undefined
@@ -682,21 +805,44 @@
      `forceLabel` flag overrides the strip's responsive label-visibility
      rule — popout children and stepped sub-view children always show
      their text labels regardless of the outer strip's collapsed state. -->
-{#snippet rowBody(item: SideBarMenuItem, isParent: boolean, forceLabel: boolean, isOpen: boolean)}
+{#snippet rowBody(
+  item: SideBarMenuItem,
+  isParent: boolean,
+  forceLabel: boolean,
+  isOpen: boolean,
+  reserveIcon: boolean,
+)}
   {@const labelClassResolved = forceLabel ? "inline" : labelClass}
   {@const chevronClass = forceLabel ? "inline-flex" : chevronVisibility}
-  <span class="relative inline-flex shrink-0 items-center justify-center {sz.iconBox} {sz.iconSvg}">
-    {#if item.icon}{@const Icon = item.icon}<Icon />{/if}
-    {#if item.badge}{@render badge(item.badge)}{/if}
-  </span>
+  <!-- 1rem gap before the trailing/chevron cluster (label ↔ chevron breathing room); mirrors under
+       `side="right"`. -->
+  {@const endGap = dockRight ? "mr-4" : "ml-4"}
+  {#if reserveIcon}
+    <span class="relative inline-flex shrink-0 items-center justify-center {sz.iconBox} {sz.iconSvg}">
+      {#if item.icon}{@const Icon = item.icon}<Icon />{/if}
+      {#if item.badge}{@render badge(item.badge)}{/if}
+    </span>
+  {/if}
   <!-- `flex-1 min-w-0 truncate` makes the label take the remaining
 	     row width AND lets it shrink below its content size, which is
 	     what `truncate` (overflow-hidden + text-ellipsis) needs to
 	     actually clip overflow. Without `min-w-0` the label refuses
 	     to shrink past its natural width and the row overflows. -->
-  <span class="flex-1 min-w-0 truncate {dockRight ? 'text-right' : ''} {labelClassResolved} {sz.text}"
-    >{item.label}</span
+  <!-- When the group reserves an icon column the box supplies the leading inset; when it doesn't,
+       give the label a 1rem leading inset so it isn't flush to the edge. -->
+  <span
+    class="flex-1 min-w-0 truncate {reserveIcon ? '' : dockRight ? 'pr-4' : 'pl-4'} {dockRight
+      ? 'text-right'
+      : ''} {labelClassResolved} {sz.text}">{item.label}</span
   >
+  {#if item.trailing}
+    <!-- Trailing slot — a state indicator / glyph on the far end. Visible with the label (like the
+         chevron); sits before the chevron on a parent row. `chevronClass` keeps it `inline-flex`. -->
+    <span
+      class="shrink-0 items-center justify-center {endGap} {sz.chevronBox} {sz.chevronSvg} {chevronClass}"
+      >{@render item.trailing()}</span
+    >
+  {/if}
   {#if isParent}
     <!-- Chevron — visible only when the label is visible (no point
 		     dangling a `>` next to an icon-only icon). Rotates 180° to
@@ -705,7 +851,7 @@
 		     `chevronVisibility` (not `labelClassResolved`) so the span
 		     stays `inline-flex` and the SVG centers vertically. -->
     <span
-      class="shrink-0 items-center justify-center opacity-60 transition-transform duration-150 {isOpen
+      class="shrink-0 items-center justify-center opacity-60 transition-transform duration-150 {endGap} {isOpen
         ? 'rotate-180'
         : ''} {sz.chevronBox} {sz.chevronSvg} {chevronClass}"
     >
@@ -715,16 +861,22 @@
 {/snippet}
 
 <!-- Single row template — used by items / bottomItems and the popout. -->
-{#snippet row(item: SideBarMenuItem, opts: { id?: ItemId; isPopoutChild?: boolean })}
+{#snippet row(
+  item: SideBarMenuItem,
+  opts: { id?: ItemId; isPopoutChild?: boolean; reserveIcon?: boolean },
+)}
   {@const active = isItemActive(item)}
-  {@const ownActive = !!item.link && pathMatches(item.link, currentPath)}
+  {@const ownActive = isItemOwnActive(item)}
+  {@const reserveIcon = opts.reserveIcon ?? true}
   {@const hasChildren = (item.children?.length ?? 0) > 0}
-  {@const isParent = (hasChildren || !!item.popout) && !opts.isPopoutChild}
+  {@const isParent = hasChildren || !!item.popout}
   {@const hasLink = !!item.link}
-  {@const isOpen = !!opts.id && openId === opts.id}
-  {@const popoutId = opts.id ? "sbm-popout-" + opts.id.replace(":", "-") : undefined}
+  {@const isOpen = !!opts.id && isOnPath(opts.id)}
+  {@const popoutId = opts.id ? popoutDomId(opts.id) : undefined}
   {@const tipSuppressed = tooltipSuppressed || !!opts.isPopoutChild}
-  {@const rowClass = `group flex items-center w-full ${sz.row} ${dockRight ? "flex-row-reverse" : ""} ${labelsVisible || opts.isPopoutChild ? (dockRight ? "pl-3" : "pr-3") : ""} transition-colors cursor-pointer ${active ? "[background-color:var(--sbm-accent)] text-white" : isOpen ? "[background-color:color-mix(in_srgb,var(--sbm-accent)_18%,transparent)]" : "hover:[background-color:color-mix(in_srgb,var(--sbm-accent)_12%,transparent)]"}`}
+  {@const enter = opts.id && popoutOnHover ? () => openOnHover(opts.id!, isParent) : undefined}
+  {@const leave = opts.id && popoutOnHover ? scheduleClose : undefined}
+  {@const rowClass = `group flex items-center w-full ${sz.row} ${dockRight ? "flex-row-reverse" : ""} ${labelsVisible || opts.isPopoutChild ? (dockRight ? "pl-4" : "pr-4") : ""} transition-colors cursor-pointer ${active ? "[background-color:var(--sbm-accent)] text-white" : isOpen ? "[background-color:color-mix(in_srgb,var(--sbm-accent)_18%,transparent)]" : "hover:[background-color:color-mix(in_srgb,var(--sbm-accent)_12%,transparent)]"}`}
   {#if hasLink}
     <a
       href={item.link}
@@ -735,13 +887,9 @@
       aria-haspopup={isParent ? "menu" : undefined}
       aria-expanded={isParent && opts.id ? isOpen : undefined}
       aria-controls={isParent && isOpen ? popoutId : undefined}
-      use:tooltip={{
-        text: item.label,
-        side: popoutSide,
-        disabled: tipSuppressed || (isParent && opts.id ? openId === opts.id : false),
-      }}
-      onmouseenter={isParent && opts.id && popoutOnHover ? () => openOnHover(opts.id!) : undefined}
-      onmouseleave={isParent && opts.id && popoutOnHover ? scheduleClose : undefined}
+      use:tooltip={{ text: item.label, side: popoutSide, disabled: tipSuppressed || isOpen }}
+      onmouseenter={enter}
+      onmouseleave={leave}
       onclick={(e) => {
         // Power-user passthrough: Shift/Cmd/Ctrl click opens in
         // a new tab — don't mutate UI state in that case.
@@ -752,13 +900,16 @@
             // Cancel default navigation so the click can't
             // follow the parent's href out from under us.
             e.preventDefault();
-            stepIntoChildren(item);
-          } else {
-            // When popouts are click-to-open (a plain icon rail), a click opens the popout
+            stepIntoChildren(item, opts.id);
+          } else if (!popoutOnHover) {
+            // Click-to-open (a plain icon rail / interactMode="click"): a click opens the popout
             // instead of following the parent's href.
-            if (!popoutOnHover) e.preventDefault();
+            e.preventDefault();
             toggleOnClick(opts.id);
           }
+          // Hover mode: the popout is governed by hover, so a click just navigates. Toggling here
+          // would fight the tap's own `mouseenter` (which already opened it) and close it — the
+          // first-tap "opens then immediately closes" bug (B1).
         } else {
           // Leaf or popout-child navigation. Reset the drawer
           // so the next open starts at the top, the stepped
@@ -767,7 +918,7 @@
         }
       }}
     >
-      {@render rowBody(item, isParent, !!opts.isPopoutChild, isOpen)}
+      {@render rowBody(item, isParent, !!opts.isPopoutChild, isOpen, reserveIcon)}
     </a>
   {:else if isParent}
     <button
@@ -775,14 +926,21 @@
       use:refIntoMap={opts.id}
       class="{rowClass} text-left"
       aria-haspopup="menu"
-      aria-expanded={openId === opts.id}
+      aria-expanded={isOpen}
       aria-controls={isOpen ? popoutId : undefined}
-      use:tooltip={{ text: item.label, side: popoutSide, disabled: tipSuppressed || openId === opts.id }}
-      onmouseenter={popoutOnHover ? () => openOnHover(opts.id!) : undefined}
-      onmouseleave={popoutOnHover ? scheduleClose : undefined}
-      onclick={() => (isStepped ? stepIntoChildren(item) : toggleOnClick(opts.id!))}
+      use:tooltip={{ text: item.label, side: popoutSide, disabled: tipSuppressed || isOpen }}
+      onmouseenter={enter}
+      onmouseleave={leave}
+      onclick={() => {
+        if (isStepped) stepIntoChildren(item, opts.id!);
+        // Hover mode: click (re)opens — never toggles closed — so a touch tap (which fires
+        // `mouseenter` then `click`) ends up OPEN instead of open-then-closed (B1). Click mode
+        // has no hover-open to fight, so it toggles as before.
+        else if (popoutOnHover) openOnHover(opts.id!, true);
+        else toggleOnClick(opts.id!);
+      }}
     >
-      {@render rowBody(item, isParent, !!opts.isPopoutChild, isOpen)}
+      {@render rowBody(item, isParent, !!opts.isPopoutChild, isOpen, reserveIcon)}
     </button>
   {:else if item.onclick}
     <!-- Action row: no link, no children/popout — a `<button>` that runs `onclick`
@@ -792,44 +950,93 @@
       use:refIntoMap={opts.id}
       class="{rowClass} text-left"
       use:tooltip={{ text: item.label, side: popoutSide, disabled: tipSuppressed }}
+      onmouseenter={enter}
+      onmouseleave={leave}
       onclick={(e) => {
         item.onclick!(e);
         closeAfterNav();
       }}
     >
-      {@render rowBody(item, false, !!opts.isPopoutChild, false)}
+      {@render rowBody(item, false, !!opts.isPopoutChild, false, reserveIcon)}
     </button>
   {:else}
     <!-- Malformed item: no link, no children. Render visibly so the
 		     consumer notices, but with disabled-style cursor + opacity. -->
     <span class="{rowClass} opacity-40 cursor-not-allowed" aria-disabled="true">
-      {@render rowBody(item, false, !!opts.isPopoutChild, false)}
+      {@render rowBody(item, false, !!opts.isPopoutChild, false, reserveIcon)}
     </span>
   {/if}
 {/snippet}
 
-<!-- Popout panel — fixed 200px (--sbm-expanded-w), edge-to-edge rows,
-     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, popoutId: string)}
+<!-- A menu node — the row plus, when it's a parent, its fly-out Popup (which recurses via
+     `popoutPanel`). This is what makes the menu multi-tier: a nested parent renders its own node
+     + Popup inside its ancestor's popout. -->
+{#snippet menuNode(
+  item: SideBarMenuItem,
+  id: ItemId,
+  group: "top" | "bottom",
+  idx: number,
+  total: number,
+  reserveIcon: boolean,
+  depth: number,
+)}
+  {@render row(item, { id, isPopoutChild: depth > 0, reserveIcon })}
+  {#if (((item.children?.length ?? 0) > 0) || !!item.popout) && !isStepped}
+    {@const top = depth === 0}
+    {@const geom = top
+      ? geometryFor(id, group, idx, total, item.children?.length ?? 1)
+      : {
+          anchor: triggerRefs[id],
+          align: "start" as const,
+          borderClass: `${dockRight ? "border-l" : "border-r"} border-t border-b`,
+        }}
+    <!-- Top-level parents (depth 0) anchor to the sidebar via the spans rule; a nested parent anchors
+         to its own trigger row and flies out further to the same side — a cascade. `lightDismiss={false}`
+         because a nested popout is "outside" its parent's top-layer element; the aside-level listener
+         below dismisses the whole chain instead. -->
+    <Popup
+      anchor={geom.anchor}
+      open={isOnPath(id)}
+      side={popoutSide}
+      align={geom.align}
+      offset={0}
+      margin={top ? 0 : 8}
+      lightDismiss={false}
+      onclose={() => {
+        if (isOnPath(id)) openId = null;
+      }}
+    >
+      {@render popoutPanel(item, id, group, geom.borderClass)}
+    </Popup>
+  {/if}
+{/snippet}
+
+<!-- Popout panel — the floating menu. Renders a custom `item.popout` snippet, else the children as
+     nested `menuNode`s (so a child that is itself a parent cascades further). `data-sbm-popout` +
+     `data-open` are consumer hooks; overflow scrolls, capped to the viewport. -->
+{#snippet popoutPanel(item: SideBarMenuItem, id: ItemId, group: "top" | "bottom", borderClass: string)}
+  {@const popoutId = popoutDomId(id)}
+  {@const isOpen = isOnPath(id)}
   <!-- svelte-ignore a11y_interactive_supports_focus -->
   <div
     role="menu"
     tabindex="-1"
     id={popoutId}
+    data-sbm-popout=""
+    data-open={isOpen}
     style="width: max-content;{expandedWidth != null ? ` max-width: ${expandedWidth}px;` : ''} --sbm-accent: {accentVar};"
-    class="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}"
+    class="overflow-y-auto overflow-x-hidden max-h-[calc(100vh-0.5rem)] 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={popoutOnHover ? cancelClose : undefined}
     onmouseleave={popoutOnHover ? scheduleClose : undefined}
   >
     {#if item.popout}
       {@render item.popout()}
     {:else}
+      {@const childReserve = anyIcon(item.children ?? [])}
       <ul class="flex flex-col">
-        {#each item.children ?? [] as child (child.label)}
+        {#each item.children ?? [] as child, ci (child.label)}
           <li class="list-none" role="none">
-            {@render row(child, { isPopoutChild: true })}
+            {@render menuNode(child, `${id}>${ci}`, group, ci, item.children!.length, childReserve, 1)}
           </li>
         {/each}
       </ul>
@@ -894,16 +1101,18 @@
 		{additionalClass}
 	"
   >
-  {#if isStepped && stepLevel === 1 && currentParent}
+  {#if isStepped && stepPath.length > 0}
     <!-- Stepped sub-view (<2xs only): show just the children of the
 		     parent the user tapped. The consumer's hamburger button is
 		     expected to flip to a `←` icon and set `stepLevel = 0` to
 		     return here — there is no in-drawer back row by design so
 		     the back affordance stays in a single, consistent spot. -->
+    {@const currentParent = stepPath[stepPath.length - 1]}
+    {@const stepReserve = anyIcon(currentParent.children ?? [])}
     <ul class="flex flex-col {scrollList}">
-      {#each currentParent.children ?? [] as child (child.label)}
+      {#each currentParent.children ?? [] as child, ci (child.label)}
         <li class="list-none">
-          {@render row(child, { isPopoutChild: true })}
+          {@render row(child, { id: `step:${ci}`, isPopoutChild: true, reserveIcon: stepReserve })}
         </li>
       {/each}
     </ul>
@@ -911,26 +1120,9 @@
     {#if items.length > 0}
       <ul class="flex flex-col {scrollList}">
         {#each items as item, idx (item.label)}
-          {@const id = `top:${idx}` as ItemId}
           <li class="list-none">
-            {@render row(item, { id })}
+            {@render menuNode(item, `top:${idx}`, "top", idx, items.length, railReserve, 0)}
           </li>
-          {#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}
-              side={popoutSide}
-              align={geom.align}
-              offset={0}
-              margin={0}
-              onclose={() => {
-                if (openId === id) openId = null;
-              }}
-            >
-              {@render popout(item, geom.borderClass, "sbm-popout-" + id.replace(":", "-"))}
-            </Popup>
-          {/if}
         {/each}
       </ul>
     {/if}
@@ -944,32 +1136,9 @@
     {#if bottomItems.length > 0}
       <ul class="flex flex-col shrink-0">
         {#each bottomItems as item, idx (item.label)}
-          {@const id = `bottom:${idx}` as ItemId}
           <li class="list-none">
-            {@render row(item, { id })}
+            {@render menuNode(item, `bottom:${idx}`, "bottom", idx, bottomItems.length, railReserve, 0)}
           </li>
-          {#if ((item.children?.length ?? 0) > 0 || !!item.popout) && !isStepped}
-            {@const geom = geometryFor(
-              id,
-              "bottom",
-              idx,
-              bottomItems.length,
-              item.children?.length ?? 1,
-            )}
-            <Popup
-              anchor={geom.anchor}
-              open={openId === id}
-              side={popoutSide}
-              align={geom.align}
-              offset={0}
-              margin={0}
-              onclose={() => {
-                if (openId === id) openId = null;
-              }}
-            >
-              {@render popout(item, geom.borderClass, "sbm-popout-" + id.replace(":", "-"))}
-            </Popup>
-          {/if}
         {/each}
       </ul>
     {/if}

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

@@ -48,6 +48,21 @@ export type SideBarMenuBadge = {
  * can't always prove it.
  */
 export type SideBarMenuItemIcon = any;
+/**
+ * How an item decides it's "active" against `currentPath`. Absent → the default
+ * `currentPath` matches `link` on a segment boundary.
+ *  - `string` / `string[]` — path prefix(es) (segment-boundary match, like `link`).
+ *  - object — `path` prefix(es) PLUS optional `query` params that must ALL match (compared against
+ *    `currentPath`'s query string, so pass `pathname + search` as `currentPath`), and `exact` to
+ *    require the path to equal rather than prefix-match. Other query params are ignored.
+ * Use it for cross-group items keyed by a query param (e.g. `?via=network`) so a module that appears
+ * in several groups only highlights in the right one.
+ */
+export type SideBarMenuActiveRule = string | string[] | {
+    path: string | string[];
+    query?: Record<string, string>;
+    exact?: boolean;
+};
 export type SideBarMenuItem = {
     /**
      * Icon component constructor — same idiom as `MenuItem.icon`. Pass an
@@ -59,7 +74,8 @@ export type SideBarMenuItem = {
     /** href; absent when the item is a parent that only hosts children. */
     link?: string;
     badge?: SideBarMenuBadge;
-    /** v1 renders only the first level; deeper levels emit a DEV warning. */
+    /** Child items — rendered as a fly-out popout. Recursive: a child that itself has children
+     *  cascades into a further popout (or steps deeper in `stepped` mode). */
     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. */
@@ -70,6 +86,13 @@ export type SideBarMenuItem = {
     /** 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;
+    /** Trailing-slot content rendered on the row's far end (after the label, before the parent chevron
+     *  if any) — a state indicator, a dock/mute/notify glyph, a count, etc. Shown wherever the label is.
+     *  Sized/positioned like the chevron; mirrors to the other edge under `side="right"`. */
+    trailing?: import("svelte").Snippet;
+    /** Override how this item computes its active state (see {@link SideBarMenuActiveRule}). Absent →
+     *  the default `currentPath` segment-boundary match against `link`. */
+    activeMatch?: SideBarMenuActiveRule;
 };
 import type { Size } from "../../types/sizes.js";
 import { type Variant } from "../../types/variants.js";
@@ -120,10 +143,10 @@ type $$ComponentProps = {
      */
     open?: boolean;
     /**
-     * Step-navigation level inside the `stepped`-mode drawer.
-     * `0` = top-level. `1` = inside a parent item's children list.
-     * Bind from the consumer so a header button can read it (e.g.
-     * to flip X → ← icon) and write it (set to `0` to navigate back).
+     * Step-navigation DEPTH inside the `stepped`-mode drawer (breadcrumb length).
+     * `0` = top-level, `1` = inside a parent's children, `2` = a grandparent's, … Bind from the
+     * consumer so a header button can read it (e.g. flip X → ← when `> 0`) and write it to go BACK
+     * one level (`stepLevel - 1`), or `0` to return to the top.
      */
     stepLevel?: number;
     /**
@@ -157,6 +180,11 @@ type $$ComponentProps = {
     /** Read-only (bindable) — the currently active {@link SideBarMenuMode}. Bind it to decide whether
      *  your own header trigger should render (e.g. only in `drawer`/`stepped`). */
     activeMode?: SideBarMenuMode;
+    /** Publish the strip's live pixel width to a CSS custom property on `:root` (kept current via a
+     *  `ResizeObserver`), so sibling layout can offset by it without its own observer. `true` →
+     *  `--sbm-current-width`; a string → that custom-property name (use a distinct name per instance
+     *  when you run more than one). Unset → nothing published. */
+    publishWidthVar?: boolean | string;
     class?: string;
 };
 declare const SideBarMenu: import("svelte").Component<$$ComponentProps, {}, "open" | "stepLevel" | "api" | "activeMode">;

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, SideBarMenuApi, SideBarMenuMode, } from "./components/SideBarMenu/SideBarMenu.svelte";
+export type { SideBarMenuItem, SideBarMenuBadge, SideBarMenuBadgeVariant, SideBarMenuApi, SideBarMenuMode, SideBarMenuActiveRule, } 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.9.0",
+  "version": "0.10.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/spaethtech/svelte-ui.git"