@spaethtech/svelte-ui 0.1.10 → 0.3.0

package/dist/components/SideBarMenu/SideBarMenu.svelte

@@ -0,0 +1,724 @@
+<!--
+/**
+ * SideBarMenu — a vertical nav strip with a top-anchored group, an optional
+ * 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}.
+ * Each item declares its own icon (Snippet), label, link, badge, and optional
+ * children. Children render in a top-layer Popup on hover or click.
+ *
+ * See `SideBarMenu.spec.md` for the full API + behavior contract.
+ */
+-->
+<script lang="ts" module>
+  /**
+   * Visual / interaction mode at a given viewport tier.
+   *
+   *  - `stepped`  — `position: absolute`, slides in from the left,
+   *                 full-width. Parent items use click-to-step
+   *                 navigation (no hover popouts). Requires a
+   *                 hamburger trigger. Designed for phones.
+   *  - `drawer`   — `position: absolute`, slides in from the left,
+   *                 `--sbm-expanded-w` wide. Parent items show hover
+   *                 popouts to the right. Requires a hamburger.
+   *                 Designed for tablet portrait / phablet.
+   *  - `icon`     — `position: relative` (in flow), `--sbm-collapsed-w`
+   *                 wide, icon-only rows. Parent items show hover
+   *                 popouts. Designed for tablet landscape / narrow
+   *                 desktop.
+   *  - `expanded` — `position: relative`, `--sbm-expanded-w` wide,
+   *                 icon + label rows. Parent items show hover popouts.
+   *                 Designed for wide desktop.
+   */
+  export type SideBarMenuMode = "stepped" | "drawer" | "icon" | "expanded";
+
+  export type SideBarMenuBadgeVariant = "error" | "warning" | "info" | "success";
+
+  export type SideBarMenuBadge = {
+    /** Color of the indicator. */
+    variant: SideBarMenuBadgeVariant;
+    /**
+     * Optional numeric count. Present → filled pill with the number.
+     * Absent → bare icon (variant-coloured). Useful for "has-any" signals
+     * where the precise count isn't meaningful to the user.
+     */
+    count?: number;
+  };
+
+  /**
+   * Icon component slot. Typed permissively because `unplugin-icons` emits
+   * its own callable shape (`typeof default`) that doesn't satisfy Svelte's
+   * strict `Component<…>` primitive in every consumer tsconfig. The runtime
+   * shape is always a Svelte component the renderer can `<Icon />` — TS just
+   * can't always prove it.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export type SideBarMenuItemIcon = any;
+
+  export type SideBarMenuItem = {
+    /**
+     * Icon component constructor — same idiom as `MenuItem.icon`. Pass an
+     * imported MDI icon (e.g. `import IconActivity from '~icons/mdi/pulse'`)
+     * straight into the data array; no snippet wrapper needed.
+     */
+    icon?: SideBarMenuItemIcon;
+    label: string;
+    /** 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. */
+    children?: SideBarMenuItem[];
+  };
+</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";
+  import IconCloseOctagon from "~icons/mdi/close-octagon";
+  import IconInformation from "~icons/mdi/information";
+  import IconCheckCircle from "~icons/mdi/check-circle";
+  import IconMenu from "~icons/mdi/menu";
+  import IconClose from "~icons/mdi/close";
+  import IconChevronRight from "~icons/mdi/chevron-right";
+  import type { Size } from "../../types/sizes.js";
+  import { BREAKPOINT_PX, type Breakpoint } from "../../types/breakpoints.js";
+
+  type ModesMap = Partial<Record<Breakpoint, SideBarMenuMode>>;
+
+  let {
+    topItems = [],
+    bottomItems = [],
+    currentPath,
+    size = "md",
+    modes,
+    collapsedAt = "lg",
+    collapsedWidth = 48,
+    expandedWidth = 200,
+    open = $bindable(false),
+    stepLevel = $bindable(0),
+    hamburger = true,
+    class: additionalClass = "",
+  }: {
+    topItems?: SideBarMenuItem[];
+    bottomItems?: SideBarMenuItem[];
+    currentPath: string;
+    size?: Size;
+    /**
+     * Per-tier visual mode. Each key in this map sets the mode at and
+     * above that breakpoint. The active mode at any viewport is the
+     * mode for the highest matching tier.
+     *
+     * When omitted, defaults to
+     * `{ base: 'stepped', '2xs': 'drawer', xs: 'icon', [collapsedAt]: 'expanded' }`
+     * so the prop is opt-in for consumers happy with the standard
+     * phone→tablet→desktop progression.
+     */
+    modes?: ModesMap;
+    /**
+     * Legacy shorthand: which tier the strip expands to icon + label
+     * at when `modes` isn't supplied. Equivalent to overriding only
+     * the `expanded` slot in the default `modes` map. Ignored when
+     * `modes` is set explicitly. Prefer passing `modes` directly.
+     */
+    collapsedAt?: Exclude<Breakpoint, "base" | "4xs" | "3xs" | "2xs" | "xs">;
+    /** Pixel width of the strip in `icon` mode. */
+    collapsedWidth?: number;
+    /** Pixel width of the strip in `expanded` mode and the slide-in drawer when open. */
+    expandedWidth?: number;
+    /**
+     * Drawer open state when the active mode is `drawer` or `stepped`.
+     * Bind from the consumer to drive it from your own header button
+     * (set `hamburger={false}` to suppress the built-in trigger).
+     * Ignored in `icon` and `expanded` modes (strip is always in-layout).
+     */
+    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).
+     */
+    stepLevel?: number;
+    /**
+     * Render the built-in fixed-position hamburger button when the
+     * active mode is `drawer` or `stepped`. Set to `false` if the
+     * consumer renders its own trigger (typically inside a header)
+     * and binds to `open`.
+     */
+    hamburger?: boolean;
+    class?: string;
+  } = $props();
+
+  // 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.
+  const effectiveModes = $derived<ModesMap>(
+    modes ?? {
+      base: "stepped",
+      "2xs": "drawer",
+      xs: "icon",
+      [collapsedAt]: "expanded",
+    },
+  );
+
+  function resolveMode(map: ModesMap, viewportPx: number): SideBarMenuMode {
+    const tiers = (Object.keys(map) as Breakpoint[]).sort(
+      (a, b) => BREAKPOINT_PX[a] - BREAKPOINT_PX[b],
+    );
+    let active: SideBarMenuMode = "expanded";
+    for (const tier of tiers) {
+      if (viewportPx >= BREAKPOINT_PX[tier]) {
+        const m = map[tier];
+        if (m) active = m;
+      }
+    }
+    return active;
+  }
+
+  // SSR-safe default — the effect below corrects on mount.
+  let currentMode = $state<SideBarMenuMode>("expanded");
+
+  $effect(() => {
+    const map = effectiveModes;
+    function sync() {
+      currentMode = resolveMode(map, window.innerWidth);
+    }
+    // One matchMedia listener per tier in the map. Cheaper than a
+    // general resize handler — only fires when the active tier
+    // actually flips.
+    const tiers = (Object.keys(map) as Breakpoint[]).filter((t) => t !== "base");
+    const queries = tiers.map((t) => window.matchMedia(`(min-width: ${BREAKPOINT_PX[t]}px)`));
+    sync();
+    queries.forEach((q) => q.addEventListener("change", sync));
+    return () => queries.forEach((q) => q.removeEventListener("change", sync));
+  });
+
+  const isStepped = $derived(currentMode === "stepped");
+  const isDrawer = $derived(currentMode === "drawer" || currentMode === "stepped");
+  const labelsVisible = $derived(currentMode !== "icon");
+
+  // ── DEV depth warning ───────────────────────────────────────────
+  if (DEV) {
+    const walk = (items: SideBarMenuItem[], depth: number) => {
+      for (const it of items) {
+        if (it.children?.length) {
+          if (depth >= 1) {
+            console.warn(
+              'SideBarMenu: nesting deeper than 1 level is not yet rendered; flattening grandchildren of "' +
+                it.label +
+                '"',
+            );
+            return;
+          }
+          walk(it.children, depth + 1);
+        }
+      }
+    };
+    walk(topItems, 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)
+  //   - Count pill  ≈ icon × 0.6  (a touch bigger to leave room for digits)
+  //   - Offsets     = (boxSize − iconSize) / 2 − badgeSize / 2 so the
+  //                   badge centers on the icon's top-right corner
+  //   - Chevron     scales with the main icon (sm 14 / md 16 / lg 20)
+  type SizeStyles = {
+    row: string;
+    iconBox: string;
+    iconSvg: string;
+    text: string;
+    badgeIcon: string; // [&_svg]:w-N [&_svg]:h-N for warning/error glyph
+    badgeIconOffset: string; // absolute top-[N] right-[N] for the icon badge
+    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
+  };
+  const sizeMap: Record<Size, SizeStyles> = {
+    sm: {
+      row: "h-10",
+      iconBox: "w-10 h-10",
+      iconSvg: "[&_svg]:w-5 [&_svg]:h-5",
+      text: "text-xs",
+      // Badge dot scales roughly 1/3 of the main icon: solid circle
+      // that occludes the corner. Span is sized directly (not via
+      // descendant svg selector) so it's exactly as specified.
+      badgeIcon: "w-1.5 h-1.5",
+      badgeIconOffset: "top-[7px] right-[7px]",
+      pill: "min-w-[12px] h-[12px]",
+      pillText: "text-[8px]",
+      pillOffset: "top-[4px] right-[4px]",
+      chevronBox: "w-5 h-5",
+      chevronSvg: "[&_svg]:w-3.5 [&_svg]:h-3.5",
+    },
+    md: {
+      row: "h-12",
+      iconBox: "w-12 h-12",
+      iconSvg: "[&_svg]:w-6 [&_svg]:h-6",
+      text: "text-sm",
+      badgeIcon: "w-2 h-2",
+      badgeIconOffset: "top-[8px] right-[8px]",
+      pill: "min-w-[14px] h-[14px]",
+      pillText: "text-[9px]",
+      pillOffset: "top-[5px] right-[5px]",
+      chevronBox: "w-6 h-6",
+      chevronSvg: "[&_svg]:w-4 [&_svg]:h-4",
+    },
+    lg: {
+      row: "h-14",
+      iconBox: "w-14 h-14",
+      iconSvg: "[&_svg]:w-7 [&_svg]:h-7",
+      text: "text-base",
+      badgeIcon: "w-2.5 h-2.5",
+      badgeIconOffset: "top-[9px] right-[9px]",
+      pill: "min-w-[16px] h-[16px]",
+      pillText: "text-[10px]",
+      pillOffset: "top-[6px] right-[6px]",
+      chevronBox: "w-7 h-7",
+      chevronSvg: "[&_svg]:w-5 [&_svg]:h-5",
+    },
+  };
+  const sz = $derived(sizeMap[size]);
+
+  // ── 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
+  // drawer. At `xs+` the strip is always visible in-layout and `open` is
+  // irrelevant. At `<2xs` the drawer is full-width and parent items use
+  // click-to-step navigation instead of hover popouts.
+  function closeDrawer() {
+    open = false;
+  }
+
+  // Reset every transient drawer state — used when a leaf navigates,
+  // so the next time the user opens the drawer they're back at the
+  // top of the menu (not still inside a stepped parent's children) and
+  // no popout is open.
+  function closeAfterNav() {
+    open = false;
+    stepLevel = 0;
+    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);
+
+  $effect(() => {
+    if (stepLevel === 0) currentParent = null;
+  });
+  $effect(() => {
+    if (!open) {
+      stepLevel = 0;
+      currentParent = null;
+    }
+  });
+
+  function stepIntoChildren(item: SideBarMenuItem) {
+    currentParent = item;
+    stepLevel = 1;
+  }
+
+  // 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
+  // with the viewport. The chevron span needs `inline-flex` (not
+  // `inline`) so its SVG stays centered; otherwise the same logic.
+  const labelClass = $derived(labelsVisible ? "inline" : "hidden");
+  const chevronVisibility = $derived(labelsVisible ? "inline-flex" : "hidden");
+  // The corresponding "label is currently visible" check used to disable
+  // tooltips at the expanded breakpoint. We don't have direct access to
+  // the media query here without an effect, so we always pass the tooltip
+  // the label text and let the tooltip's own `disabled` option be flipped
+  // off by the popout-open state; when the label is on-screen the user
+  // has no reason to hover for it anyway.
+
+  // ── Active state ────────────────────────────────────────────────
+  function isItemActive(item: SideBarMenuItem): boolean {
+    if (item.link && currentPath.startsWith(item.link)) return true;
+    if (item.children?.length) return item.children.some(isItemActive);
+    return false;
+  }
+
+  // ── Hover/click open state ──────────────────────────────────────
+  type ItemId = `top:${number}` | `bottom:${number}`;
+
+  let openId = $state<ItemId | null>(null);
+  let closeTimer: ReturnType<typeof setTimeout> | null = null;
+  const CLOSE_GRACE_MS = 150;
+
+  function cancelClose() {
+    if (closeTimer !== null) {
+      clearTimeout(closeTimer);
+      closeTimer = null;
+    }
+  }
+  function scheduleClose() {
+    cancelClose();
+    closeTimer = setTimeout(() => {
+      openId = null;
+      closeTimer = null;
+    }, CLOSE_GRACE_MS);
+  }
+  function openOnHover(id: ItemId) {
+    cancelClose();
+    if (openId !== id) openId = id;
+  }
+  function toggleOnClick(id: ItemId) {
+    cancelClose();
+    openId = openId === id ? null : id;
+  }
+
+  // ── Refs ────────────────────────────────────────────────────────
+  let asideRef = $state<HTMLElement | undefined>();
+  // One ref per parent trigger. Keyed by ItemId so Popup can anchor.
+  const triggerRefs = $state<Record<string, HTMLElement | undefined>>({});
+
+  // 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
+  // (popout-child rows pass no id since they're never anchors themselves).
+  function refIntoMap(node: HTMLElement, id: ItemId | undefined) {
+    if (id) triggerRefs[id] = node;
+    return {
+      update(newId: ItemId | undefined) {
+        if (newId) triggerRefs[newId] = node;
+      },
+      destroy() {
+        if (id) triggerRefs[id] = undefined;
+      },
+    };
+  }
+
+  // Spans rule — see SideBarMenu.spec.md → Popout Positioning.
+  function spansEdge(group: "top" | "bottom", idx: number, total: number, count: number) {
+    // positionFromEnd: how many rows from the anchored edge inclusive.
+    const positionFromEnd = group === "bottom" ? total - idx : idx + 1;
+    return count >= positionFromEnd;
+  }
+
+  function geometryFor(
+    id: ItemId,
+    group: "top" | "bottom",
+    idx: number,
+    total: number,
+    count: number,
+  ): {
+    anchor: HTMLElement | undefined;
+    align: "start" | "end";
+    borderClass: string;
+  } {
+    const spans = spansEdge(group, idx, total, count);
+    // Border policy:
+    //   - Right border is always needed (popout meets free content
+    //     area on the right).
+    //   - Top/bottom borders are needed only on edges that DON'T
+    //     coincide with the sidebar's edge. When `spans` is true,
+    //     the popout's edge on the anchored side is flush with the
+    //     sidebar's top/bottom — that edge gets no border. The
+    //     opposite edge always extends into the sidebar's middle
+    //     vertical range, so it always gets a border.
+    //   - When `spans` is false the popout sits at the trigger row
+    //     level; both top and bottom edges are mid-sidebar and need
+    //     borders.
+    //   - Left border never — the sidebar's own `border-right`
+    //     covers that seam.
+    // NOTE: very tall popouts that would exceed the sidebar's
+    // height get clamped to the viewport by the `anchored` engine
+    // boundary. That case also needs in-popout scroll (TODO) and
+    // the border rule may need to account for viewport-edge cases.
+    let borderClass = "border-r";
+    if (group === "bottom") {
+      borderClass += spans ? " border-t" : " border-t border-b";
+    } else {
+      borderClass += spans ? " border-b" : " border-t border-b";
+    }
+    if (group === "bottom") {
+      return spans
+        ? { anchor: asideRef, align: "end", borderClass }
+        : { anchor: triggerRefs[id], align: "start", borderClass };
+    }
+    return spans
+      ? { anchor: asideRef, align: "start", borderClass }
+      : { anchor: triggerRefs[id], align: "end", borderClass };
+  }
+</script>
+
+<!-- Badge slot — count omitted = solid colored dot covering the icon's
+     top-right corner; count present = solid pill with the number. Both
+     have an opaque background that occludes the main icon underneath so
+     the badge always reads as "on top of" the icon. All sizing /
+     positioning comes from `sizeMap` and scales with the `size` prop. -->
+{#snippet badge(b: SideBarMenuBadge)}
+  {@const colorVar = `var(--ui-color-${b.variant})`}
+  {#if b.count === undefined}
+    <span
+      class="absolute {sz.badgeIconOffset} inline-block rounded-full {sz.badgeIcon}"
+      style="background-color: {colorVar};"
+      aria-hidden="true"
+    ></span>
+  {:else}
+    <span
+      class="absolute {sz.pillOffset} inline-flex items-center justify-center rounded-full px-1 {sz.pill} {sz.pillText} font-semibold leading-none"
+      style="background-color: {colorVar}; color: white;"
+      aria-hidden="true"
+    >
+      {b.count}
+    </span>
+  {/if}
+{/snippet}
+
+<!-- Inner content of a row — icon (+ optional badge), label (truncated
+     when wider than the row), and a `>` chevron on parent items so
+     the user can see at a glance which items host children. The
+     `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)}
+  {@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>
+  <!-- `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 {labelClassResolved} {sz.text}">{item.label}</span>
+  {#if isParent}
+    <!-- Chevron — visible only when the label is visible (no point
+		     dangling a `>` next to an icon-only icon). Rotates 180° to
+		     `<` whenever the parent is open OR being hovered, with a
+		     `transition-transform` so it eases in/out. Uses
+		     `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}"
+    >
+      <IconChevronRight />
+    </span>
+  {/if}
+{/snippet}
+
+<!-- Single row template — used by topItems / bottomItems and the popout. -->
+{#snippet row(item: SideBarMenuItem, opts: { id?: ItemId; isPopoutChild?: boolean })}
+  {@const active = isItemActive(item)}
+  {@const hasChildren = (item.children?.length ?? 0) > 0}
+  {@const isParent = hasChildren && !opts.isPopoutChild}
+  {@const hasLink = !!item.link}
+  {@const isOpen = !!opts.id && openId === opts.id}
+  {@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}
+      use:tooltip={{
+        text: item.label,
+        side: "right",
+        disabled: isParent && opts.id ? openId === opts.id : false,
+      }}
+      onmouseenter={isParent && opts.id && !isStepped ? () => openOnHover(opts.id!) : undefined}
+      onmouseleave={isParent && opts.id && !isStepped ? scheduleClose : undefined}
+      onclick={(e) => {
+        // Power-user passthrough: Shift/Cmd/Ctrl click opens in
+        // a new tab — don't mutate UI state in that case.
+        if (e.shiftKey || e.metaKey || e.ctrlKey) return;
+        if (isParent && opts.id) {
+          if (isStepped) {
+            // At <2xs: tap parent → step into its children.
+            // Cancel default navigation so the click can't
+            // follow the parent's href out from under us.
+            e.preventDefault();
+            stepIntoChildren(item);
+          } else {
+            toggleOnClick(opts.id);
+          }
+        } else {
+          // Leaf or popout-child navigation. Reset the drawer
+          // so the next open starts at the top, the stepped
+          // sub-view doesn't linger, and any open popout closes.
+          closeAfterNav();
+        }
+      }}
+    >
+      {@render rowBody(item, isParent, !!opts.isPopoutChild, isOpen)}
+    </a>
+  {:else if isParent}
+    <button
+      type="button"
+      use:refIntoMap={opts.id}
+      class="{rowClass} text-left"
+      aria-haspopup="menu"
+      aria-expanded={openId === opts.id}
+      use:tooltip={{ text: item.label, side: "right", disabled: openId === opts.id }}
+      onmouseenter={!isStepped ? () => openOnHover(opts.id!) : undefined}
+      onmouseleave={!isStepped ? scheduleClose : undefined}
+      onclick={() => (isStepped ? stepIntoChildren(item) : toggleOnClick(opts.id!))}
+    >
+      {@render rowBody(item, isParent, !!opts.isPopoutChild, isOpen)}
+    </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)}
+    </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)}
+  <!-- svelte-ignore a11y_interactive_supports_focus -->
+  <div
+    role="menu"
+    tabindex="-1"
+    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>
+  </div>
+{/snippet}
+
+{#if hamburger && isDrawer}
+  <!-- Built-in hamburger — fixed top-left. Only rendered when the
+	     active mode is `drawer` or `stepped`. Set `hamburger={false}`
+	     to suppress this when the consumer provides its own trigger. -->
+  <button
+    type="button"
+    class="fixed top-3 left-3 z-[80] inline-flex w-10 h-10 items-center justify-center cursor-pointer [background-color:var(--ui-color-background)] border [border-color:color-mix(in_srgb,var(--ui-color-text)_15%,transparent)] shadow-md [&_svg]:w-5 [&_svg]:h-5"
+    aria-label={open ? "Close menu" : "Open menu"}
+    aria-expanded={open}
+    onclick={() => (open = !open)}
+  >
+    {#if open}<IconClose />{:else}<IconMenu />{/if}
+  </button>
+{/if}
+
+<!-- Backdrop for the mobile drawer. Click anywhere on it to close.
+     Only rendered when the active mode is `drawer` or `stepped` AND
+     the drawer is open. -->
+{#if isDrawer && open}
+  <!-- svelte-ignore a11y_click_events_have_key_events a11y_no_static_element_interactions -->
+  <div
+    class="absolute inset-0 z-[70] [background-color:color-mix(in_srgb,black_30%,transparent)]"
+    onclick={closeDrawer}
+  ></div>
+{/if}
+
+<aside
+  bind:this={asideRef}
+  style="--sbm-collapsed-w: {collapsedWidth}px; --sbm-expanded-w: {expandedWidth}px;"
+  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)]'}
+		{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
+		     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. -->
+    <ul class="flex flex-col">
+      {#each currentParent.children ?? [] as child (child.label)}
+        <li class="list-none">
+          {@render row(child, { isPopoutChild: true })}
+        </li>
+      {/each}
+    </ul>
+  {:else}
+    {#if topItems.length > 0}
+      <ul class="flex flex-col">
+        {#each topItems 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)}
+            <Popup
+              anchor={geom.anchor}
+              open={openId === id}
+              side="right"
+              align={geom.align}
+              offset={0}
+              onclose={() => {
+                if (openId === id) openId = null;
+              }}
+            >
+              {@render popout(item, geom.borderClass)}
+            </Popup>
+          {/if}
+        {/each}
+      </ul>
+    {/if}
+
+    {#if topItems.length > 0 && bottomItems.length > 0}
+      <div class="flex-1"></div>
+    {/if}
+
+    {#if bottomItems.length > 0}
+      <ul class="flex flex-col">
+        {#each bottomItems as item, idx (item.label)}
+          {@const id = `bottom:${idx}` as ItemId}
+          <li class="list-none">
+            {@render row(item, { id })}
+          </li>
+          {#if (item.children?.length ?? 0) > 0 && !isStepped}
+            {@const geom = geometryFor(
+              id,
+              "bottom",
+              idx,
+              bottomItems.length,
+              item.children!.length,
+            )}
+            <Popup
+              anchor={geom.anchor}
+              open={openId === id}
+              side="right"
+              align={geom.align}
+              offset={0}
+              onclose={() => {
+                if (openId === id) openId = null;
+              }}
+            >
+              {@render popout(item, geom.borderClass)}
+            </Popup>
+          {/if}
+        {/each}
+      </ul>
+    {/if}
+  {/if}
+</aside>