@waggylabs/yumekit 0.4.3 → 0.4.4

package/dist/components/y-appbar.js

@@ -1,4 +1,4 @@
-import { contrastTextColor, resolveAnchor } from '../../modules/helpers.js';
+import { contrastTextColor, createElement, resolveAnchor } from '../../modules/helpers.js';
 import { getIcon } from '../../icons/registry.js';
 
 class YumeButton extends HTMLElement {
@@ -782,16 +782,6 @@ if (!customElements.get("y-icon")) {
     customElements.define("y-icon", YumeIcon);
 }
 
-var chevronRight = "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\">\n  <polyline points=\"9 18 15 12 9 6\"/>\n</svg>\n";
-
-var chevronDown = "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\">\n  <polyline points=\"6 9 12 15 18 9\"/>\n</svg>\n";
-
-var expandLeft = "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\">\n  <polyline points=\"11 17 6 12 11 7\"/>\n  <polyline points=\"18 17 13 12 18 7\"/>\n</svg>\n";
-
-var expandRight = "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\">\n  <polyline points=\"13 17 18 12 13 7\"/>\n  <polyline points=\"6 17 11 12 6 7\"/>\n</svg>\n";
-
-var menu = "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\">\n  <line x1=\"4\" y1=\"6\" x2=\"20\" y2=\"6\"/>\n  <line x1=\"4\" y1=\"12\" x2=\"20\" y2=\"12\"/>\n  <line x1=\"4\" y1=\"18\" x2=\"20\" y2=\"18\"/>\n</svg>\n";
-
 class YumeMenu extends HTMLElement {
     static get observedAttributes() {
         return ["items", "anchor", "visible", "direction", "size", "history"];
@@ -807,6 +797,8 @@ class YumeMenu extends HTMLElement {
         this._onAnchorClick = this._onAnchorClick.bind(this);
         this._onDocumentClick = this._onDocumentClick.bind(this);
         this._onScrollOrResize = this._onScrollOrResize.bind(this);
+        this._isReady = false;
+        this._slottedHandlers = new Map();
     }
 
     connectedCallback() {
@@ -823,10 +815,13 @@ class YumeMenu extends HTMLElement {
         this.style.zIndex = "1000";
         this.style.display = "none";
         if (this.visible) this._updatePosition();
+
+        this._isReady = true;
     }
 
     disconnectedCallback() {
         this._teardownAnchor();
+        this._teardownSlottedItems();
 
         document.removeEventListener("click", this._onDocumentClick);
         window.removeEventListener("scroll", this._onScrollOrResize, true);
@@ -846,6 +841,13 @@ class YumeMenu extends HTMLElement {
         if (name === "visible" || name === "direction") {
             this._updatePosition();
         }
+
+        if (name === "visible" && this._isReady) {
+            this.dispatchEvent(new CustomEvent(this.visible ? "open" : "close", {
+                bubbles: true,
+                composed: true,
+            }));
+        }
     }
 
     // -------------------------------------------------------------------------
@@ -860,6 +862,16 @@ class YumeMenu extends HTMLElement {
     get direction() { return this.getAttribute("direction") || "down"; }
     set direction(val) { this.setAttribute("direction", val); }
 
+    /**
+     * Navigation mode: omit for pushState (SPA-friendly), set to "false" for full-page navigation.
+     * Regardless of this setting, a cancelable "navigate" event is always dispatched first.
+     */
+    get history() { return this.getAttribute("history"); }
+    set history(val) {
+        if (val != null) this.setAttribute("history", val);
+        else this.removeAttribute("history");
+    }
+
     /** Menu items array (JSON attribute). */
     get items() {
         try {
@@ -872,16 +884,6 @@ class YumeMenu extends HTMLElement {
         this.setAttribute("items", Array.isArray(val) ? JSON.stringify(val) : (val ?? "[]"));
     }
 
-    /**
-     * Navigation mode: omit for pushState (SPA-friendly), set to "false" for full-page navigation.
-     * Regardless of this setting, a cancelable "navigate" event is always dispatched first.
-     */
-    get history() { return this.getAttribute("history"); }
-    set history(val) {
-        if (val != null) this.setAttribute("history", val);
-        else this.removeAttribute("history");
-    }
-
     /** Size: "small" | "medium" | "large" (default "medium"). */
     get size() {
         const sz = this.getAttribute("size");
@@ -905,63 +907,94 @@ class YumeMenu extends HTMLElement {
     render() {
         this.shadowRoot.innerHTML = "";
 
-        const style = document.createElement("style");
-        style.textContent = this._buildStyles();
-        this.shadowRoot.appendChild(style);
+        const style = createElement("style", {}, [this._buildStyles()]);
 
-        const rootUl = this._createMenuList(this.items);
-        rootUl.classList.add("menu");
-        rootUl.setAttribute("role", "menu");
-        rootUl.setAttribute("part", "menu");
+        const root = this._createMenuList(this.items);
+        root.classList.add("menu");
+        root.setAttribute("role", "menu");
+        root.setAttribute("part", "menu");
 
-        this.shadowRoot.appendChild(rootUl);
+        const childSlot = createElement("slot");
+        childSlot.addEventListener("slotchange", () => this._processSlottedItems());
+        root.appendChild(childSlot);
+
+        this.shadowRoot.appendChild(style);
+        this.shadowRoot.appendChild(root);
+        this._processSlottedItems();
     }
 
     // -------------------------------------------------------------------------
     // Private
     // -------------------------------------------------------------------------
 
+    _activateItem(item) {
+        if (item.children?.length > 0) return;
+
+        this._dispatchSelect({
+            value: item.value ?? item.text,
+            item,
+        });
+
+        const href = item.href ?? item.url;
+        if (href) this._navigateTo(href);
+
+        this.visible = false;
+    }
+
+    _activateSlottedItem(el) {
+        this._dispatchSelect({
+            value: el.dataset.value ?? el.textContent.trim(),
+            element: el,
+        });
+        this.visible = false;
+    }
+
     _buildStyles() {
         const paddingVar = `var(--component-button-padding-${this.size}, 0.5rem)`;
         return `
-            ul.menu,
-            ul.submenu {
-                list-style: none;
-                margin: 0;
-                padding: 0;
+            .menu,
+            .submenu {
                 background: var(--component-menu-background, #0c0c0d);
                 border: var(--component-menu-border-width, 1px) solid var(--component-menu-border-color, #37383a);
                 border-radius: var(--component-menu-border-radius, 4px);
                 box-shadow: var(--component-menu-shadow, 0 2px 8px rgba(0, 0, 0, 0.15));
                 min-width: 150px;
+                display: flex;
+                flex-direction: column;
             }
 
-            li.menuitem {
+            .menuitem,
+            ::slotted(:not([slot])) {
                 cursor: pointer;
                 padding: ${paddingVar};
-                display: flex;
-                align-items: center;
-                justify-content: space-between;
                 white-space: nowrap;
                 color: var(--component-menu-color, #f7f7fa);
                 font-size: var(--font-size-button, 1em);
+                box-sizing: border-box;
+            }
+
+            .menuitem {
+                display: flex;
+                align-items: center;
+                justify-content: space-between;
                 position: relative;
             }
 
-            li.menuitem:hover {
+            .menuitem:hover,
+            ::slotted(:not([slot]):hover) {
                 background: var(--component-menu-hover-background, #292a2b);
             }
 
-            li.menuitem.selected {
+            .menuitem.selected {
                 background: var(--component-menu-selected-background);
                 color: var(--component-menu-selected-color);
             }
 
-            li.menuitem.selected:hover {
+            .menuitem.selected:hover {
                 background: var(--component-menu-selected-background);
             }
 
-            ul.submenu {
+            .submenu {
                 position: absolute;
                 top: 0;
                 left: 100%;
@@ -969,8 +1002,8 @@ class YumeMenu extends HTMLElement {
                 z-index: var(--component-menu-z-index, 1001);
             }
 
-            li.menuitem:hover > ul.submenu {
-                display: block;
+            .menuitem:hover > .submenu {
+                display: flex;
             }
 
             .submenu-indicator {
@@ -980,13 +1013,11 @@ class YumeMenu extends HTMLElement {
                 opacity: 0.6;
             }
 
-            .submenu-indicator svg {
-                width: 16px;
-                height: 16px;
-            }
-
             .item-content {
                 flex: 1;
+                display: inline-flex;
+                align-items: center;
+                gap: 0.5rem;
             }
         `;
     }
@@ -999,91 +1030,140 @@ class YumeMenu extends HTMLElement {
         });
     }
 
-    _createMenuList(items) {
-        const ul = document.createElement("ul");
-
-        items.forEach((item) => {
-            const li = document.createElement("li");
-            li.className = item.selected ? "menuitem selected" : "menuitem";
-            li.setAttribute("role", "menuitem");
-            li.setAttribute("part", item.selected ? "menuitem selected" : "menuitem");
-            li.setAttribute("aria-current", item.selected ? "true" : "false");
-            li.tabIndex = 0;
-
-            const contentWrapper = document.createElement("span");
-            contentWrapper.className = "item-content";
-
-            if (item["icon-template"]) {
-                const iconTpl = this._findTemplate(item["icon-template"]);
-                if (iconTpl)
-                    contentWrapper.appendChild(iconTpl.content.cloneNode(true));
-            }
-
-            if (item.template) {
-                const textTpl = this._findTemplate(item.template);
-                if (textTpl) {
-                    contentWrapper.appendChild(textTpl.content.cloneNode(true));
-                } else {
-                    contentWrapper.append(item.text);
-                }
-            } else {
-                contentWrapper.append(item.text);
-            }
+    _computeMenuOffset(direction, anchorRect, menuRect, vw, vh) {
+        if (direction === "right") {
+            let top = anchorRect.top;
+            let left = anchorRect.right;
+            if (left + menuRect.width > vw) left = anchorRect.left - menuRect.width;
+            if (top + menuRect.height > vh) top = anchorRect.top - menuRect.height;
+            return { top, left };
+        }
 
-            li.appendChild(contentWrapper);
+        if (direction === "up") {
+            let top = anchorRect.top - menuRect.height;
+            let left = anchorRect.left;
+            if (top < 0) top = anchorRect.bottom;
+            if (left + menuRect.width > vw) left = vw - menuRect.width - 10;
+            return { top, left };
+        }
 
-            if (item.url) {
-                li.addEventListener("click", () => {
-                    const event = new CustomEvent("navigate", {
-                        bubbles: true,
-                        composed: true,
-                        cancelable: true,
-                        detail: { href: item.url },
-                    });
-                    const cancelled = !this.dispatchEvent(event);
-                    if (cancelled) return;
-                    if (this.getAttribute("history") !== "false") {
-                        history.pushState({}, "", item.url);
-                        window.dispatchEvent(new PopStateEvent("popstate", { state: {} }));
-                    } else {
-                        window.location.href = item.url;
-                    }
-                });
-            }
+        if (direction === "left") {
+            let top = anchorRect.top;
+            let left = anchorRect.left - menuRect.width;
+            if (left < 0) left = anchorRect.right;
+            if (top + menuRect.height > vh) top = anchorRect.top - menuRect.height;
+            return { top, left };
+        }
 
-            if (!item.children?.length) {
-                li.addEventListener("click", () => {
-                    this.visible = false;
-                });
-            }
+        // "down" (default)
+        let top = anchorRect.bottom;
+        let left = anchorRect.left;
+        if (top + menuRect.height > vh) top = anchorRect.top - menuRect.height;
+        if (left + menuRect.width > vw) left = vw - menuRect.width - 10;
+        return { top, left };
+    }
 
-            if (item.children?.length) {
-                const indicator = document.createElement("span");
-                indicator.className = "submenu-indicator";
-                indicator.innerHTML = chevronRight;
-                li.appendChild(indicator);
+    _createItemContent(item) {
+        const wrapper = createElement("span", { class: "item-content" });
 
-                const submenu = this._createMenuList(item.children);
-                submenu.classList.add("submenu");
-                submenu.setAttribute("role", "menu");
-                li.appendChild(submenu);
-            }
+        if (item.icon) {
+            wrapper.appendChild(createElement("y-icon", { name: item.icon, size: this.size }));
+        } else if (item["icon-template"]) {
+            YumeMenu._warnTemplateFieldDeprecated();
+            const tpl = this._findTemplate(item["icon-template"]);
+            if (tpl) wrapper.appendChild(tpl.content.cloneNode(true));
+        }
+
+        if (item.template) {
+            YumeMenu._warnTemplateFieldDeprecated();
+            const tpl = this._findTemplate(item.template);
+            if (tpl) wrapper.appendChild(tpl.content.cloneNode(true));
+            else wrapper.append(item.text ?? "");
+        } else {
+            wrapper.append(item.text ?? "");
+        }
+
+        if (!item.slot) return wrapper;
+
+        const slotEl = createElement("slot", { name: item.slot });
+        slotEl.appendChild(wrapper);
+        return slotEl;
+    }
 
-            ul.appendChild(li);
+    _createMenuItem(item) {
+        const isSelected = !!item.selected;
+        const partValue = isSelected ? "menuitem selected" : "menuitem";
+
+        const itemEl = createElement("div", {
+            class: partValue,
+            role: "menuitem",
+            part: partValue,
+            "aria-current": isSelected ? "true" : "false",
+            tabindex: "0",
         });
 
-        return ul;
+        itemEl.appendChild(this._createItemContent(item));
+
+        if (item.url && !item.href) YumeMenu._warnUrlDeprecated();
+
+        itemEl.addEventListener("click", () => this._activateItem(item));
+
+        if (item.children?.length > 0) {
+            itemEl.appendChild(this._createSubmenuIndicator());
+
+            const submenu = this._createMenuList(item.children);
+            submenu.classList.add("submenu");
+            submenu.setAttribute("role", "menu");
+            itemEl.appendChild(submenu);
+        }
+
+        return itemEl;
+    }
+
+    _createMenuList(items) {
+        const container = createElement("div");
+        items.forEach((item) => container.appendChild(this._createMenuItem(item)));
+        return container;
+    }
+
+    _createSubmenuIndicator() {
+        return createElement("span", { class: "submenu-indicator" }, [
+            createElement("y-icon", { name: "chevron-right", size: this.size }),
+        ]);
+    }
+
+    _dispatchSelect(detail) {
+        this.dispatchEvent(new CustomEvent("select", {
+            detail,
+            bubbles: true,
+            composed: true,
+        }));
     }
 
     _findTemplate(name) {
         return this.querySelector(`template[slot="${name}"]`);
     }
 
+    _navigateTo(href) {
+        const event = new CustomEvent("navigate", {
+            bubbles: true,
+            composed: true,
+            cancelable: true,
+            detail: { href },
+        });
+        if (!this.dispatchEvent(event)) return;
+
+        if (this.getAttribute("history") === "false") {
+            window.location.href = href;
+        } else {
+            history.pushState({}, "", href);
+            window.dispatchEvent(new PopStateEvent("popstate", { state: {} }));
+        }
+    }
+
     _onAnchorClick(e) {
         e.stopPropagation();
-        if (!this.visible) {
-            YumeMenu._closeAll(this);
-        }
+        if (!this.visible) YumeMenu._closeAll(this);
         this.visible = !this.visible;
     }
 
@@ -1098,9 +1178,34 @@ class YumeMenu extends HTMLElement {
         if (this.visible) this._updatePosition();
     }
 
+    _processSlottedItems() {
+        const slot = this.shadowRoot.querySelector(".menu > slot");
+        if (!slot) return;
+
+        const assigned = new Set(slot.assignedElements());
+
+        for (const [el, handler] of this._slottedHandlers) {
+            if (assigned.has(el)) continue;
+            el.removeEventListener("click", handler);
+            this._slottedHandlers.delete(el);
+        }
+
+        for (const el of assigned) {
+            if (this._slottedHandlers.has(el)) continue;
+
+            if (!el.hasAttribute("role")) el.setAttribute("role", "menuitem");
+            if (el.tabIndex < 0) el.tabIndex = 0;
+
+            const handler = () => this._activateSlottedItem(el);
+            el.addEventListener("click", handler);
+            this._slottedHandlers.set(el, handler);
+        }
+    }
+
     _setupAnchor() {
         const id = this.anchor;
         if (!id) return;
+
         const root = this.getRootNode();
         this._anchorResolveDispose = resolveAnchor(
             this,
@@ -1124,6 +1229,13 @@ class YumeMenu extends HTMLElement {
         }
     }
 
+    _teardownSlottedItems() {
+        for (const [el, handler] of this._slottedHandlers) {
+            el.removeEventListener("click", handler);
+        }
+        this._slottedHandlers.clear();
+    }
+
     _updatePosition() {
         if (!this.visible || !this._anchorEl) {
             this.style.display = "none";
@@ -1132,7 +1244,7 @@ class YumeMenu extends HTMLElement {
 
         const anchorRect = this._anchorEl.getBoundingClientRect();
 
-        // Temporarily show off-screen to measure actual dimensions
+        // Measure menu off-screen so we know its size before placing it.
         this.style.visibility = "hidden";
         this.style.display = "block";
         const menuRect = this.getBoundingClientRect();
@@ -1140,58 +1252,38 @@ class YumeMenu extends HTMLElement {
 
         const vw = window.innerWidth;
         const vh = window.innerHeight;
+        const { top, left } = this._computeMenuOffset(
+            this.direction,
+            anchorRect,
+            menuRect,
+            vw,
+            vh,
+        );
 
-        let top, left;
-
-        if (this.direction === "right") {
-            top = anchorRect.top;
-            left = anchorRect.right;
-
-            if (left + menuRect.width > vw) {
-                left = anchorRect.left - menuRect.width;
-            }
-            if (top + menuRect.height > vh) {
-                top = anchorRect.top - menuRect.height;
-            }
-        } else if (this.direction === "up") {
-            top = anchorRect.top - menuRect.height;
-            left = anchorRect.left;
-
-            if (top < 0) {
-                top = anchorRect.bottom;
-            }
-            if (left + menuRect.width > vw) {
-                left = vw - menuRect.width - 10;
-            }
-        } else if (this.direction === "left") {
-            top = anchorRect.top;
-            left = anchorRect.left - menuRect.width;
-
-            if (left < 0) {
-                left = anchorRect.right;
-            }
-            if (top + menuRect.height > vh) {
-                top = anchorRect.top - menuRect.height;
-            }
-        } else {
-            // "down" (default)
-            top = anchorRect.bottom;
-            left = anchorRect.left;
+        const clampedTop = Math.max(0, Math.min(top, vh - menuRect.height));
+        const clampedLeft = Math.max(0, Math.min(left, vw - menuRect.width));
 
-            if (top + menuRect.height > vh) {
-                top = anchorRect.top - menuRect.height;
-            }
-            if (left + menuRect.width > vw) {
-                left = vw - menuRect.width - 10;
-            }
-        }
+        this.style.top = `${clampedTop}px`;
+        this.style.left = `${clampedLeft}px`;
+        this.style.display = "block";
+    }
 
-        top = Math.max(0, Math.min(top, vh - menuRect.height));
-        left = Math.max(0, Math.min(left, vw - menuRect.width));
+    static _warnTemplateFieldDeprecated() {
+        if (YumeMenu._templateFieldDeprecationWarned) return;
+        YumeMenu._templateFieldDeprecationWarned = true;
+        // eslint-disable-next-line no-console
+        console.warn(
+            "[y-menu] item.template and item['icon-template'] are deprecated; use item.icon (icon name) and item.slot (named slot) instead. Support will be removed in a future release.",
+        );
+    }
 
-        this.style.top = `${top}px`;
-        this.style.left = `${left}px`;
-        this.style.display = "block";
+    static _warnUrlDeprecated() {
+        if (YumeMenu._urlDeprecationWarned) return;
+        YumeMenu._urlDeprecationWarned = true;
+        // eslint-disable-next-line no-console
+        console.warn(
+            "[y-menu] item.url is deprecated; use item.href instead. Support for item.url will be removed in a future release.",
+        );
     }
 }
 
@@ -1249,6 +1341,7 @@ class YumeAppbar extends HTMLElement {
         this._idCounter = 0;
         this._mql = null;
         this._isMobile = false;
+        this._mobileOutsideClick = null;
     }
 
     connectedCallback() {
@@ -1258,6 +1351,7 @@ class YumeAppbar extends HTMLElement {
 
     disconnectedCallback() {
         this._teardownMediaQuery();
+        this._teardownMobileOutsideClick();
     }
 
     attributeChangedCallback(name, oldVal, newVal) {
@@ -1273,12 +1367,26 @@ class YumeAppbar extends HTMLElement {
     // -------------------------------------------------------------------------
 
     /** Whether the sidebar is currently collapsed. */
-    get collapsed() { return this.hasAttribute("collapsed"); }
+    get collapsed() {
+        return this.hasAttribute("collapsed");
+    }
     set collapsed(val) {
         if (val) this.setAttribute("collapsed", "");
         else this.removeAttribute("collapsed");
     }
 
+    /**
+     * Navigation mode: omit for pushState (SPA-friendly), set to "false" for full-page navigation.
+     * Regardless of this setting, a cancelable "navigate" event is always dispatched first.
+     */
+    get history() {
+        return this.getAttribute("history");
+    }
+    set history(val) {
+        if (val != null) this.setAttribute("history", val);
+        else this.removeAttribute("history");
+    }
+
     /** Nav items array parsed from the "items" attribute. */
     get items() {
         try {
@@ -1287,47 +1395,53 @@ class YumeAppbar extends HTMLElement {
             return [];
         }
     }
-    set items(val) { this.setAttribute("items", JSON.stringify(val)); }
+    set items(val) {
+        this.setAttribute("items", JSON.stringify(val));
+    }
 
     /**
      * Direction menus pop out from nav buttons:
      * "right", "down", or unset (auto: vertical → right, horizontal → down).
      */
-    get menuDirection() { return this.getAttribute("menu-direction") || ""; }
+    get menuDirection() {
+        return this.getAttribute("menu-direction") || "";
+    }
     set menuDirection(val) {
         if (val) this.setAttribute("menu-direction", val);
         else this.removeAttribute("menu-direction");
     }
 
     /** Whether the appbar is currently rendering in mobile mode. */
-    get mobile() { return this._isMobile; }
+    get mobile() {
+        return this._isMobile;
+    }
 
     /**
      * Override the mobile breakpoint (in pixels) for this instance.
      * Falls back to the CSS variable --component-appbar-mobile-breakpoint (default 768).
      */
-    get mobileBreakpoint() { return this.getAttribute("mobile-breakpoint") || ""; }
+    get mobileBreakpoint() {
+        return this.getAttribute("mobile-breakpoint") || "";
+    }
     set mobileBreakpoint(val) {
         if (val) this.setAttribute("mobile-breakpoint", val);
         else this.removeAttribute("mobile-breakpoint");
     }
 
     /** Layout orientation: "vertical" | "horizontal" (default "vertical"). */
-    get orientation() { return this.getAttribute("orientation") || "vertical"; }
-    set orientation(val) { this.setAttribute("orientation", val); }
+    get orientation() {
+        return this.getAttribute("orientation") || "vertical";
+    }
+    set orientation(val) {
+        this.setAttribute("orientation", val);
+    }
 
     /** Size variant: "small" | "medium" | "large" (default "medium"). */
-    get size() { return this.getAttribute("size") || "medium"; }
-    set size(val) { this.setAttribute("size", val); }
-
-    /**
-     * Navigation mode: omit for pushState (SPA-friendly), set to "false" for full-page navigation.
-     * Regardless of this setting, a cancelable "navigate" event is always dispatched first.
-     */
-    get history() { return this.getAttribute("history"); }
-    set history(val) {
-        if (val != null) this.setAttribute("history", val);
-        else this.removeAttribute("history");
+    get size() {
+        return this.getAttribute("size") || "medium";
+    }
+    set size(val) {
+        this.setAttribute("size", val);
     }
 
     /** Sticky position: "start" | "end" | false. */
@@ -1344,201 +1458,88 @@ class YumeAppbar extends HTMLElement {
     // Public
     // -------------------------------------------------------------------------
 
+    render() {
+        if (this._isMobile) this._renderMobile();
+        else this._renderDesktop();
+    }
+
     /** Toggles the collapsed state of the sidebar. */
     toggle() {
         this.collapsed = !this.collapsed;
     }
 
-    render() {
-        if (this._isMobile) {
-            this._renderMobile();
-        } else {
-            this._renderDesktop();
-        }
-    }
-
     // -------------------------------------------------------------------------
     // Private
     // -------------------------------------------------------------------------
 
-    _buildCollapseButton(cfg, isCollapsed) {
-        const btn = document.createElement("y-button");
-        btn.setAttribute("color", "base");
-        btn.setAttribute("style-type", "flat");
-        btn.setAttribute("size", cfg.buttonSize);
-        btn.setAttribute("aria-label", isCollapsed ? "Expand sidebar" : "Collapse sidebar");
-        btn.className = "collapse-btn";
-
-        const icon = document.createElement("span");
-        icon.slot = "left-icon";
-        icon.innerHTML = isCollapsed ? expandRight : expandLeft;
-        btn.appendChild(icon);
-
-        if (!isCollapsed) {
-            btn.appendChild(document.createTextNode("Collapse"));
-        }
-
-        btn.addEventListener("click", this._onCollapseClick);
-        return btn;
-    }
-
-    _buildHeader() {
-        const header = document.createElement("div");
-        header.className = "appbar-header";
-        header.setAttribute("part", "header");
-
-        const headerContent = document.createElement("div");
-        headerContent.className = "header-content";
-
-        const logoWrapper = document.createElement("div");
-        logoWrapper.className = "logo-wrapper";
-        logoWrapper.appendChild(this._makeSlot("logo"));
-        headerContent.appendChild(logoWrapper);
+    _buildBody(cfg, isCollapsed, menuDir) {
+        const body = createElement("div", { class: "appbar-body", part: "body" });
 
-        const titleWrapper = document.createElement("div");
-        titleWrapper.className = "header-title";
-        titleWrapper.appendChild(this._makeSlot("title"));
-        headerContent.appendChild(titleWrapper);
+        this.items.forEach((item) => {
+            body.appendChild(
+                this._buildNavItem(item, cfg, isCollapsed, menuDir),
+            );
+        });
+        body.appendChild(createElement("slot", {}));
 
-        header.appendChild(headerContent);
-        header.appendChild(this._makeSlot("header"));
-        return header;
+        return body;
     }
 
-    _buildNavItem(item, cfg, isVertical, isCollapsed, menuDir) {
-        const hasChildren = item.children?.length > 0;
-        const wrapper = document.createElement("div");
-        const btn = document.createElement("y-button");
-        const btnId = this._uid("appbar-btn");
-
-        wrapper.className = "nav-item";
-        btn.id = btnId;
-        btn.setAttribute("color", this._isItemActive(item) ? "primary" : "base");
-        btn.setAttribute("style-type", "flat");
-        btn.setAttribute("size", cfg.buttonSize);
-
-        if (item.icon) {
-            if (item.icon.trim().startsWith("<")) {
-                const iconEl = document.createElement("span");
-                iconEl.slot = "left-icon";
-                iconEl.setAttribute("part", "icon");
-                iconEl.innerHTML = item.icon;
-                btn.appendChild(iconEl);
-            } else {
-                const iconEl = document.createElement("y-icon");
-                iconEl.slot = "left-icon";
-                iconEl.setAttribute("part", "icon");
-                iconEl.setAttribute("name", item.icon);
-                iconEl.setAttribute("size", cfg.iconSize);
-                btn.appendChild(iconEl);
-            }
-        }
-
-        if (item.text && !isCollapsed) {
-            btn.appendChild(document.createTextNode(item.text));
-        }
-
-        if (hasChildren && !isCollapsed) {
-            const arrow = document.createElement("span");
-            arrow.slot = "right-icon";
-            arrow.innerHTML = isVertical ? chevronRight : chevronDown;
-            btn.appendChild(arrow);
-        }
-
-        if (item.href && !hasChildren) {
-            btn.addEventListener("click", () => {
-                const event = new CustomEvent("navigate", {
-                    bubbles: true,
-                    composed: true,
-                    cancelable: true,
-                    detail: { href: item.href },
-                });
-                const cancelled = !this.dispatchEvent(event);
-                if (cancelled) return;
-                if (this.getAttribute("history") !== "false") {
-                    history.pushState({}, "", item.href);
-                    window.dispatchEvent(new PopStateEvent("popstate", { state: {} }));
-                } else {
-                    window.location.href = item.href;
-                }
-            });
-        }
-
-        if (item.slot) {
-            const slot = this._makeSlot(item.slot);
-            slot.appendChild(btn);
-            wrapper.appendChild(slot);
-        } else {
-            wrapper.appendChild(btn);
-        }
-
-        if (hasChildren) {
-            const menuEl = document.createElement("y-menu");
-            menuEl.setAttribute("anchor", btnId);
-            menuEl.setAttribute("direction", menuDir);
-            menuEl.setAttribute("size", cfg.buttonSize);
-            menuEl.items = item.children;
-            wrapper.appendChild(menuEl);
-        }
+    _buildCollapseButton(cfg, isCollapsed) {
+        const icon = createElement("y-icon", {
+            slot: "left-icon",
+            name: isCollapsed ? "expand-right" : "expand-left",
+            size: cfg.iconSize,
+        });
 
-        return wrapper;
-    }
+        const children = isCollapsed ? [icon] : [icon, "Collapse"];
+        const btn = createElement(
+            "y-button",
+            {
+                class: "collapse-btn",
+                color: "base",
+                "style-type": "flat",
+                size: cfg.buttonSize,
+                "aria-label": isCollapsed
+                    ? "Expand sidebar"
+                    : "Collapse sidebar",
+            },
+            children,
+        );
 
-    _getBreakpointPx() {
-        const attr = this.mobileBreakpoint;
-        if (attr) {
-            const px = parseInt(attr, 10);
-            if (!isNaN(px) && px > 0) return px;
-        }
-        const cssVal = getComputedStyle(document.documentElement)
-            .getPropertyValue("--component-appbar-mobile-breakpoint")
-            .trim();
-        if (cssVal) {
-            const px = parseInt(cssVal, 10);
-            if (!isNaN(px) && px > 0) return px;
-        }
-        return 768;
+        btn.addEventListener("click", this._onCollapseClick);
+        return btn;
     }
 
-    _initRender() {
-        this.shadowRoot.innerHTML = "";
-        this._idCounter = 0;
-    }
+    _buildDesktopBar(cfg, isVertical, isCollapsed, menuDir) {
+        const classes = ["appbar", isVertical ? "vertical" : "horizontal"];
+        if (isCollapsed) classes.push("collapsed");
 
-    _isItemActive(item) {
-        if (item.selected) return true;
-        if (item.href) {
-            const loc = window.location;
-            const current = loc.pathname + loc.search + loc.hash;
-            return item.href === current || item.href === loc.href;
-        }
-        return false;
-    }
+        const bar = createElement("div", {
+            class: classes.join(" "),
+            role: "navigation",
+        });
 
-    _makeSlot(name) {
-        const slot = document.createElement("slot");
-        slot.name = name;
-        return slot;
-    }
+        // Layout-specific sizing tokens consumed by the stylesheet.
+        const iconColWidth = `calc(${cfg.collapsedWidth} - 2 * var(--_appbar-padding) - 2 * var(--component-appbar-border-width, var(--component-sidebar-border-width, 2px)) - 2 * var(--component-button-border-width, 1px))`;
+        bar.style.setProperty("--_appbar-padding", cfg.padding);
+        bar.style.setProperty("--_appbar-collapsed-width", cfg.collapsedWidth);
+        bar.style.setProperty("--_appbar-body-gap", cfg.bodyGap);
+        bar.style.setProperty(
+            "--_button-padding",
+            `var(--component-button-padding-${cfg.buttonSize})`,
+        );
+        bar.style.setProperty("--_icon-col-width", iconColWidth);
 
-    _onCollapseClick() {
-        this.toggle();
-    }
+        bar.appendChild(this._buildHeader());
+        bar.appendChild(this._buildBody(cfg, isCollapsed, menuDir));
+        bar.appendChild(this._buildFooter(cfg, isVertical, isCollapsed));
 
-    _onMediaChange(e) {
-        this._isMobile = e.matches;
-        this.render();
+        return bar;
     }
 
-    _renderDesktop() {
-        this._initRender();
-        const isVertical = this.orientation === "vertical";
-        const isCollapsed = this.collapsed && isVertical;
-        const cfg = SIZE_CONFIG[this.size] || SIZE_CONFIG.medium;
-        const menuDir = this.menuDirection || (isVertical ? "right" : "down");
-
-        const style = document.createElement("style");
-        style.textContent = `
+    _buildDesktopStyles() {
+        return `
             :host {
                 display: block;
                 font-family: var(--font-family-body, sans-serif);
@@ -1766,55 +1767,148 @@ class YumeAppbar extends HTMLElement {
             ::slotted(*) {
                 display: block;
             }
+            .appbar.vertical ::slotted(:not([slot])) {
+                width: 100%;
+            }
+            .appbar.horizontal ::slotted(:not([slot])) {
+                display: inline-flex;
+                align-items: center;
+            }
+            .appbar.vertical.collapsed ::slotted(:not([slot])) {
+                width: var(--_icon-col-width);
+                overflow: hidden;
+            }
             span[slot="left-icon"] svg,
             span[slot="right-icon"] svg {
                 width: var(--component-icon-size-large, 1.25em);
                 height: var(--component-icon-size-large, 1.25em);
             }
         `;
-        this.shadowRoot.appendChild(style);
+    }
+
+    _buildFooter(cfg, isVertical, isCollapsed) {
+        const footer = createElement("div", { class: "appbar-footer", part: "footer" });
+        footer.appendChild(createElement("slot", { name: "footer" }));
+
+        if (isVertical) {
+            footer.appendChild(this._buildCollapseButton(cfg, isCollapsed));
+        }
+
+        return footer;
+    }
+
+    _buildHeader() {
+        const logoWrapper = createElement("div", { class: "logo-wrapper" }, [
+            createElement("slot", { name: "logo" }),
+        ]);
+        const titleWrapper = createElement("div", { class: "header-title" }, [
+            createElement("slot", { name: "title" }),
+        ]);
+        const headerContent = createElement("div", { class: "header-content" }, [
+            logoWrapper,
+            titleWrapper,
+        ]);
+
+        return createElement("div", { class: "appbar-header", part: "header" }, [
+            headerContent,
+            createElement("slot", { name: "header" }),
+        ]);
+    }
+
+    _buildItemIcon(iconValue, cfg) {
+        // Raw SVG markup is preserved as a public escape hatch; everything else
+        // routes through y-icon for consistent sizing/theming.
+        if (iconValue.trim().startsWith("<")) {
+            const span = createElement("span", { slot: "left-icon", part: "icon" });
+            span.innerHTML = iconValue;
+            return span;
+        }
+        return createElement("y-icon", {
+            slot: "left-icon",
+            part: "icon",
+            name: iconValue,
+            size: cfg.iconSize,
+        });
+    }
 
-        const bar = document.createElement("div");
-        bar.className = `appbar ${isVertical ? "vertical" : "horizontal"}`;
-        if (isCollapsed) bar.classList.add("collapsed");
-        bar.setAttribute("role", "navigation");
+    _buildMobileBar(cfg) {
+        const bar = createElement("div", { class: "appbar", role: "navigation" });
         bar.style.setProperty("--_appbar-padding", cfg.padding);
-        bar.style.setProperty("--_appbar-collapsed-width", cfg.collapsedWidth);
-        bar.style.setProperty("--_appbar-body-gap", cfg.bodyGap);
-        bar.style.setProperty("--_button-padding", `var(--component-button-padding-${cfg.buttonSize})`);
-        bar.style.setProperty(
-            "--_icon-col-width",
-            `calc(${cfg.collapsedWidth} - 2 * var(--_appbar-padding) - 2 * var(--component-appbar-border-width, var(--component-sidebar-border-width, 2px)) - 2 * var(--component-button-border-width, 1px))`,
-        );
 
-        bar.appendChild(this._buildHeader());
+        bar.appendChild(this._buildMobileStart(cfg));
+        bar.appendChild(this._buildMobileCenter());
+        bar.appendChild(this._buildMobileEnd());
+
+        return bar;
+    }
+
+    _buildMobileCenter() {
+        return createElement("div", { class: "mobile-center" }, [
+            createElement("slot", { name: "logo" }),
+            createElement("slot", { name: "title" }),
+        ]);
+    }
+
+    _buildMobileEnd() {
+        return createElement("div", { class: "mobile-end", part: "footer" }, [
+            createElement("slot", { name: "footer" }),
+        ]);
+    }
 
-        const body = document.createElement("div");
-        body.className = "appbar-body";
-        body.setAttribute("part", "body");
+    _buildMobileStart(cfg) {
+        const menuBtnId = this._uid("appbar-mobile-menu");
+        const panelId = this._uid("appbar-mobile-panel");
+
+        const menuBtn = createElement(
+            "y-button",
+            {
+                id: menuBtnId,
+                color: "base",
+                "style-type": "flat",
+                size: cfg.buttonSize,
+                "aria-label": "Open menu",
+                "aria-controls": panelId,
+                "aria-expanded": "false",
+            },
+            [
+                createElement("y-icon", {
+                    slot: "left-icon",
+                    name: "menu",
+                    size: cfg.iconSize,
+                }),
+            ],
+        );
+
+        const panel = createElement("div", { id: panelId, class: "mobile-panel" });
         this.items.forEach((item) => {
-            body.appendChild(this._buildNavItem(item, cfg, isVertical, isCollapsed, menuDir));
+            panel.appendChild(this._buildNavItem(item, cfg, false, "down"));
         });
-        bar.appendChild(body);
+        panel.appendChild(createElement("slot", {}));
 
-        const footer = document.createElement("div");
-        footer.className = "appbar-footer";
-        footer.setAttribute("part", "footer");
-        footer.appendChild(this._makeSlot("footer"));
-        if (isVertical) {
-            footer.appendChild(this._buildCollapseButton(cfg, isCollapsed));
-        }
-        bar.appendChild(footer);
+        const closePanel = () => {
+            panel.classList.remove("open");
+            menuBtn.setAttribute("aria-expanded", "false");
+        };
 
-        this.shadowRoot.appendChild(bar);
-    }
+        menuBtn.addEventListener("click", (e) => {
+            e.stopPropagation();
+            const open = panel.classList.toggle("open");
+            menuBtn.setAttribute("aria-expanded", open ? "true" : "false");
+        });
 
-    _renderMobile() {
-        this._initRender();
-        const cfg = SIZE_CONFIG[this.size] || SIZE_CONFIG.medium;
+        panel.addEventListener("navigate", closePanel);
 
-        const style = document.createElement("style");
-        style.textContent = `
+        this._mobileOutsideClick = (e) => {
+            if (e.composedPath().includes(this)) return;
+            closePanel();
+        };
+        document.addEventListener("pointerdown", this._mobileOutsideClick);
+
+        return createElement("div", { class: "mobile-start" }, [menuBtn, panel]);
+    }
+
+    _buildMobileStyles() {
+        return `
             :host {
                 display: block;
                 font-family: var(--font-family-body, sans-serif);
@@ -1855,6 +1949,7 @@ class YumeAppbar extends HTMLElement {
                 display: flex;
                 align-items: center;
                 flex-shrink: 0;
+                position: relative;
             }
 
             .mobile-center {
@@ -1871,8 +1966,38 @@ class YumeAppbar extends HTMLElement {
                 flex-shrink: 0;
             }
 
-            .mobile-end ::slotted(*) {
+            .mobile-panel {
+                position: absolute;
+                top: 100%;
+                left: 0;
+                margin-top: 4px;
+                background: var(--component-appbar-background, #0c0c0d);
+                border: var(--component-appbar-border-width, var(--component-sidebar-border-width, 2px)) solid var(--component-appbar-border-color, #37383a);
+                border-radius: var(--component-appbar-border-radius, var(--component-sidebar-border-radius, 4px));
+                padding: var(--_appbar-padding);
+                display: none;
+                flex-direction: column;
+                gap: 2px;
+                min-width: 180px;
+                z-index: var(--component-appbar-z-index, 100);
+            }
+            .mobile-panel.open {
+                display: flex;
+            }
+            .mobile-panel .nav-item {
+                display: flex;
+                width: 100%;
+            }
+            .mobile-panel .nav-item y-button {
                 display: block;
+                width: 100%;
+            }
+            .mobile-panel .nav-item y-button::part(button) {
+                width: 100%;
+                justify-content: flex-start;
+            }
+            .mobile-panel ::slotted(:not([slot])) {
+                width: 100%;
             }
 
             ::slotted(*) {
@@ -1884,56 +2009,147 @@ class YumeAppbar extends HTMLElement {
                 height: var(--component-icon-size-large, 1.25em);
             }
         `;
-        this.shadowRoot.appendChild(style);
+    }
 
-        const bar = document.createElement("div");
-        bar.className = "appbar";
-        bar.setAttribute("role", "navigation");
-        bar.style.setProperty("--_appbar-padding", cfg.padding);
+    _buildNavItem(item, cfg, isCollapsed, menuDir) {
+        const hasChildren = item.children?.length > 0;
+        const showLabel = item.text && !isCollapsed;
+        const showArrow = hasChildren && !isCollapsed;
+        const btnId = this._uid("appbar-btn");
+
+        const btn = createElement("y-button", {
+            id: btnId,
+            color: this._isItemActive(item) ? "primary" : "base",
+            "style-type": "flat",
+            size: cfg.buttonSize,
+        });
 
-        /* ── Left: hamburger button ── */
-        const startSection = document.createElement("div");
-        startSection.className = "mobile-start";
+        if (item.icon) btn.appendChild(this._buildItemIcon(item.icon, cfg));
+        if (showLabel) btn.appendChild(document.createTextNode(item.text));
+        if (showArrow) {
+            btn.appendChild(
+                createElement("y-icon", {
+                    slot: "right-icon",
+                    name: `chevron-${menuDir}`,
+                    size: cfg.iconSize,
+                }),
+            );
+        }
 
-        const menuBtn = document.createElement("y-button");
-        const menuBtnId = this._uid("appbar-mobile-menu");
-        menuBtn.id = menuBtnId;
-        menuBtn.setAttribute("color", "base");
-        menuBtn.setAttribute("style-type", "flat");
-        menuBtn.setAttribute("size", cfg.buttonSize);
-        menuBtn.setAttribute("aria-label", "Open menu");
-
-        const menuIcon = document.createElement("span");
-        menuIcon.slot = "left-icon";
-        menuIcon.innerHTML = menu;
-        menuBtn.appendChild(menuIcon);
-        startSection.appendChild(menuBtn);
-
-        const navItems = this.items;
-        if (navItems.length > 0) {
-            const mobileMenu = document.createElement("y-menu");
-            mobileMenu.setAttribute("anchor", menuBtnId);
-            mobileMenu.setAttribute("direction", "down");
-            mobileMenu.setAttribute("size", cfg.buttonSize);
-            mobileMenu.items = this._toMenuItems(navItems);
-            startSection.appendChild(mobileMenu);
+        if (item.href && !hasChildren) {
+            btn.addEventListener("click", () => this._navigateTo(item.href));
+        }
+
+        const wrapper = createElement("div", { class: "nav-item" });
+        if (item.slot) {
+            const slot = createElement("slot", { name: item.slot });
+            slot.appendChild(btn);
+            wrapper.appendChild(slot);
+        } else {
+            wrapper.appendChild(btn);
+        }
+
+        if (hasChildren) {
+            const menuEl = createElement("y-menu", {
+                anchor: btnId,
+                direction: menuDir,
+                size: cfg.buttonSize,
+            });
+            menuEl.items = item.children;
+            wrapper.appendChild(menuEl);
+        }
+
+        return wrapper;
+    }
+
+    _getBreakpointPx() {
+        const attr = this.mobileBreakpoint;
+        if (attr) {
+            const px = parseInt(attr, 10);
+            if (!isNaN(px) && px > 0) return px;
+        }
+
+        const cssVal = getComputedStyle(document.documentElement)
+            .getPropertyValue("--component-appbar-mobile-breakpoint")
+            .trim();
+        if (cssVal) {
+            const px = parseInt(cssVal, 10);
+            if (!isNaN(px) && px > 0) return px;
         }
-        bar.appendChild(startSection);
-
-        /* ── Center: logo + title ── */
-        const centerSection = document.createElement("div");
-        centerSection.className = "mobile-center";
-        centerSection.appendChild(this._makeSlot("logo"));
-        centerSection.appendChild(this._makeSlot("title"));
-        bar.appendChild(centerSection);
-
-        /* ── Right: footer slot ── */
-        const endSection = document.createElement("div");
-        endSection.className = "mobile-end";
-        endSection.setAttribute("part", "footer");
-        endSection.appendChild(this._makeSlot("footer"));
-        bar.appendChild(endSection);
 
+        return 768;
+    }
+
+    _initRender() {
+        this._teardownMobileOutsideClick();
+        this.shadowRoot.innerHTML = "";
+        this._idCounter = 0;
+    }
+
+    _isItemActive(item) {
+        if (item.selected) return true;
+        if (!item.href) return false;
+
+        const loc = window.location;
+        const current = loc.pathname + loc.search + loc.hash;
+
+        return item.href === current || item.href === loc.href;
+    }
+
+    _navigateTo(href) {
+        const event = new CustomEvent("navigate", {
+            bubbles: true,
+            composed: true,
+            cancelable: true,
+            detail: { href },
+        });
+        if (!this.dispatchEvent(event)) return;
+
+        if (this.getAttribute("history") === "false") {
+            window.location.href = href;
+        } else {
+            history.pushState({}, "", href);
+            window.dispatchEvent(new PopStateEvent("popstate", { state: {} }));
+        }
+    }
+
+    _onCollapseClick() {
+        this.toggle();
+    }
+
+    _onMediaChange(e) {
+        this._isMobile = e.matches;
+        this.render();
+    }
+
+    _renderDesktop() {
+        this._initRender();
+
+        const isVertical = this.orientation === "vertical";
+        const isCollapsed = this.collapsed && isVertical;
+        const cfg = SIZE_CONFIG[this.size] || SIZE_CONFIG.medium;
+        const menuDir = this.menuDirection || (isVertical ? "right" : "down");
+
+        const style = createElement("style", {}, [this._buildDesktopStyles()]);
+        const bar = this._buildDesktopBar(
+            cfg,
+            isVertical,
+            isCollapsed,
+            menuDir,
+        );
+
+        this.shadowRoot.appendChild(style);
+        this.shadowRoot.appendChild(bar);
+    }
+
+    _renderMobile() {
+        this._initRender();
+        const cfg = SIZE_CONFIG[this.size] || SIZE_CONFIG.medium;
+
+        const style = createElement("style", {}, [this._buildMobileStyles()]);
+        const bar = this._buildMobileBar(cfg);
+
+        this.shadowRoot.appendChild(style);
         this.shadowRoot.appendChild(bar);
     }
 
@@ -1950,26 +2166,15 @@ class YumeAppbar extends HTMLElement {
     }
 
     _teardownMediaQuery() {
-        if (this._mql) {
-            this._mql.removeEventListener("change", this._onMediaChange);
-            this._mql = null;
-        }
+        if (!this._mql) return;
+        this._mql.removeEventListener("change", this._onMediaChange);
+        this._mql = null;
     }
 
-    /**
-     * Convert appbar nav items to y-menu item format.
-     * Maps `href` → `url` and recursively converts children.
-     */
-    _toMenuItems(items) {
-        return items.map((item) => {
-            const mi = { text: item.text || "" };
-            if (item.href) mi.url = item.href;
-            if (item.icon) mi.icon = item.icon;
-            if (item.children?.length) {
-                mi.children = this._toMenuItems(item.children);
-            }
-            return mi;
-        });
+    _teardownMobileOutsideClick() {
+        if (!this._mobileOutsideClick) return;
+        document.removeEventListener("pointerdown", this._mobileOutsideClick);
+        this._mobileOutsideClick = null;
     }
 
     _uid(prefix) {