@spectrum-web-components/menu 1.12.0-testing.20260223092154 → 1.12.0

package/src/Menu.dev.js

@@ -11,15 +11,20 @@ var __decorateClass = (decorators, target, key, kind) => {
 };
 import {
   html,
+  render,
   SizedMixin,
   SpectrumElement
 } from "@spectrum-web-components/base";
 import {
   property,
-  query
+  query,
+  state
 } from "@spectrum-web-components/base/src/decorators.js";
 import { RovingTabindexController } from "@spectrum-web-components/reactive-controllers/src/RovingTabindex.js";
+import "@spectrum-web-components/icons-ui/icons/sp-icon-arrow500.js";
+import "../sp-menu-divider.dev.js";
 import menuStyles from "./menu.css.js";
+import { MenuItem } from "./MenuItem.dev.js";
 export class Menu extends SizedMixin(SpectrumElement, { noDefaultSize: true }) {
   constructor() {
     super();
@@ -81,8 +86,78 @@ export class Menu extends SizedMixin(SpectrumElement, { noDefaultSize: true }) {
      * @see {@link packages/overlay/src/LongpressController.ts} for longpress duration
      */
     this.scrollTimeThreshold = 300;
+    /**
+     * Capture-phase keydown handler that overrides the default
+     * `RovingTabindexController` wrap behavior at the mobile drill-down
+     * boundary:
+     *   - ArrowUp on the first nested item moves focus to the back row.
+     *   - ArrowDown on the back row moves focus to the first nested item.
+     *
+     * Runs in the capture phase so it preempts the projected submenu's
+     * controller, which handles arrow keys in the bubble phase.
+     */
+    this.handleMobileDrilldownKeydownCapture = (event) => {
+      if (event.defaultPrevented || !this.rovingTabindexController) {
+        return;
+      }
+      const { key, target } = event;
+      if (!(target instanceof MenuItem)) {
+        return;
+      }
+      const mobileRoot = this._mobileViewRoot;
+      if ((mobileRoot == null ? void 0 : mobileRoot.currentMobileSubmenu) && key === "ArrowUp") {
+        const items = this.childItems.filter((c) => this.isFocusableElement(c));
+        const firstNonBack = items.find(
+          (c) => !c.classList.contains("mobile-back-button")
+        );
+        if (firstNonBack === target) {
+          event.preventDefault();
+          event.stopImmediatePropagation();
+          mobileRoot._focusMobileBackRow();
+        }
+        return;
+      }
+      if (this.mobileView && this._mobileSubmenuStack.length > 0 && key === "ArrowDown" && target.classList.contains("mobile-back-button")) {
+        event.preventDefault();
+        event.stopImmediatePropagation();
+        this._focusFirstItemInCurrentNestedSubmenu();
+      }
+    };
+    /**
+     * Cleans up the `mobile-transition` attribute once the CSS slide
+     * animation finishes, preventing the animation from replaying on
+     * subsequent layout changes. Bound declaratively via `@animationend`
+     * on the wrapper, so it only fires for that element.
+     */
+    this._handleAnimationEnd = (event) => {
+      const target = event.currentTarget;
+      target == null ? void 0 : target.removeAttribute("mobile-transition");
+    };
+    /**
+     * Handles click on the mobile back button. Stops the event from
+     * reaching parent menus and closes the current mobile submenu.
+     */
+    this.handleMobileBackClick = (event) => {
+      event.stopPropagation();
+      event.preventDefault();
+      this.closeMobileSubmenu();
+    };
+    /**
+     * Maps each projected submenu element to its Lit render container so
+     * that back button elements can be individually cleaned up when a
+     * submenu is restored, without affecting other levels in the stack.
+     */
+    this._mobileBackContainers = /* @__PURE__ */ new Map();
+    /**
+     * Maps each projected submenu element to its original parent so the
+     * element can be moved back when the submenu is closed.
+     */
+    this._mobileSubmenuOriginalParents = /* @__PURE__ */ new Map();
     this.label = "";
     this.ignore = false;
+    this.mobileView = false;
+    this.mobileBackLabel = "Back";
+    this._mobileSubmenuStack = [];
     this.value = "";
     this.valueSeparator = ",";
     this._selected = [];
@@ -104,6 +179,10 @@ export class Menu extends SizedMixin(SpectrumElement, { noDefaultSize: true }) {
     this.descendentOverlays = /* @__PURE__ */ new Map();
     this.handleSubmenuClosed = (event) => {
       event.stopPropagation();
+      if (this.mobileView) {
+        this.resetMobileSubmenus();
+        return;
+      }
       const target = event.composedPath()[0];
       target.dispatchEvent(
         new Event("sp-menu-submenu-closed", {
@@ -170,6 +249,11 @@ export class Menu extends SizedMixin(SpectrumElement, { noDefaultSize: true }) {
     this.addEventListener("touchend", this.handlePointerup);
     this.addEventListener("focusout", this.handleFocusout);
     this.addEventListener("sp-menu-item-keydown", this.handleKeydown);
+    this.addEventListener(
+      "keydown",
+      this.handleMobileDrilldownKeydownCapture,
+      true
+    );
     this.addEventListener("pointerup", this.handlePointerup);
     this.addEventListener("sp-opened", this.handleSubmenuOpened);
     this.addEventListener("sp-closed", this.handleSubmenuClosed);
@@ -186,6 +270,12 @@ export class Menu extends SizedMixin(SpectrumElement, { noDefaultSize: true }) {
   get isSubmenu() {
     return this.slot === "submenu";
   }
+  asMenu(element) {
+    return element;
+  }
+  get _mobileViewRoot() {
+    return this.closest("sp-menu[mobile-view]");
+  }
   // milliseconds
   /**
    * Public getter for scrolling state
@@ -197,6 +287,328 @@ export class Menu extends SizedMixin(SpectrumElement, { noDefaultSize: true }) {
   set isScrolling(value) {
     this.isCurrentlyScrolling = value;
   }
+  /**
+   * Returns the MenuItem whose submenu is currently displayed at the
+   * top of the mobile drill-down stack, or `undefined` when no submenu
+   * is open.
+   */
+  get currentMobileSubmenu() {
+    return this._mobileSubmenuStack[this._mobileSubmenuStack.length - 1];
+  }
+  /**
+   * Opens a mobile submenu by projecting its content into this menu's
+   * light DOM, pushing it onto the submenu stack, triggering the
+   * slide-in animation, and focusing the back button.
+   *
+   * @param item - The MenuItem whose submenu should be opened.
+   */
+  openMobileSubmenu(item) {
+    this._projectMobileSubmenu(item);
+    this._mobileSubmenuStack = [...this._mobileSubmenuStack, item];
+    this._triggerMobileTransition("forward");
+    this._focusProjectedSubmenu(item);
+  }
+  /**
+   * Closes the topmost mobile submenu by restoring it to its original
+   * parent MenuItem, popping it from the stack, and either re-focusing
+   * the previous submenu's back button or returning focus to the
+   * triggering MenuItem when no deeper level remains.
+   */
+  closeMobileSubmenu() {
+    const closedItem = this.currentMobileSubmenu;
+    if (closedItem) {
+      this._restoreMobileSubmenu(closedItem);
+    }
+    this._mobileSubmenuStack = this._mobileSubmenuStack.slice(0, -1);
+    const previous = this.currentMobileSubmenu;
+    if (previous == null ? void 0 : previous.submenuElement) {
+      previous.submenuElement.setAttribute("slot", "mobile-submenu");
+      this._focusProjectedSubmenu(previous);
+    } else if (closedItem) {
+      this.updateComplete.then(() => {
+        closedItem.focus();
+      });
+    }
+    this._triggerMobileTransition("back");
+  }
+  /**
+   * Focuses the mobile back button inside the given item's projected
+   * submenu. Explicitly resets `tabIndex` and `focused` on every other
+   * child of the submenu so only the back row is in the tab order
+   * after the drill-down opens. We avoid delegating to the projected
+   * submenu's `RovingTabindexController` here because the back button
+   * is appended dynamically via `render()` and may not yet be in the
+   * controller's element cache when this runs, which would cause
+   * focus to fall back to the first nested item instead.
+   *
+   * @param item - The MenuItem whose projected submenu should receive focus.
+   */
+  async _focusProjectedSubmenu(item) {
+    const submenuEl = item.submenuElement;
+    if (!submenuEl) {
+      return;
+    }
+    const backItem = submenuEl.querySelector(
+      ".mobile-back-button"
+    );
+    if (!backItem) {
+      return;
+    }
+    await backItem.updateComplete;
+    const submenu = this.asMenu(submenuEl);
+    await submenu.updateComplete;
+    submenu.childItems.forEach((child) => {
+      child.tabIndex = -1;
+      child.focused = false;
+    });
+    backItem.tabIndex = 0;
+    backItem.focused = true;
+    if (submenu.rovingTabindexController) {
+      submenu.rovingTabindexController.currentIndex = submenu.childItems.indexOf(backItem);
+    }
+    backItem.focus();
+  }
+  /**
+   * Focuses the mobile back button of the currently visible projected
+   * submenu. Used when the user presses ArrowUp from the first nested
+   * item so focus moves to the back row instead of wrapping. Manages
+   * `tabIndex`/`focused` explicitly to keep the back row as the only
+   * tabbable element in the projected submenu.
+   */
+  _focusMobileBackRow() {
+    var _a;
+    const submenuEl = (_a = this.currentMobileSubmenu) == null ? void 0 : _a.submenuElement;
+    if (!submenuEl) {
+      return;
+    }
+    const backItem = submenuEl.querySelector(
+      ".mobile-back-button"
+    );
+    if (!backItem) {
+      return;
+    }
+    const submenu = this.asMenu(submenuEl);
+    submenu.childItems.forEach((child) => {
+      child.tabIndex = -1;
+      child.focused = false;
+    });
+    backItem.tabIndex = 0;
+    backItem.focused = true;
+    if (submenu.rovingTabindexController) {
+      submenu.rovingTabindexController.currentIndex = submenu.childItems.indexOf(backItem);
+    }
+    backItem.focus();
+  }
+  /**
+   * Focuses the first focusable item inside the currently visible
+   * projected submenu, skipping the back row. Used when the user
+   * presses ArrowDown from the back row. Manages `tabIndex`/`focused`
+   * explicitly so only the focused item is in the tab order.
+   */
+  _focusFirstItemInCurrentNestedSubmenu() {
+    var _a;
+    const submenuEl = (_a = this.currentMobileSubmenu) == null ? void 0 : _a.submenuElement;
+    if (!submenuEl) {
+      return;
+    }
+    const submenu = this.asMenu(submenuEl);
+    const firstItem = submenu.childItems.find(
+      (child) => !child.disabled && !child.classList.contains("mobile-back-button")
+    );
+    if (!firstItem) {
+      return;
+    }
+    submenu.childItems.forEach((child) => {
+      child.tabIndex = -1;
+      child.focused = false;
+    });
+    firstItem.tabIndex = 0;
+    firstItem.focused = true;
+    if (submenu.rovingTabindexController) {
+      submenu.rovingTabindexController.currentIndex = submenu.childItems.indexOf(firstItem);
+    }
+    firstItem.focus();
+  }
+  /**
+   * Triggers a CSS slide animation on the mobile submenu wrapper.
+   * Waits for the current Lit update cycle, then sets the
+   * `mobile-transition` attribute so the keyframe animation plays.
+   *
+   * @param direction - `'forward'` slides content in from the right,
+   *   `'back'` slides content in from the left.
+   */
+  _triggerMobileTransition(direction) {
+    this.updateComplete.then(() => {
+      var _a;
+      const wrapper = (_a = this.shadowRoot) == null ? void 0 : _a.querySelector(
+        ".mobile-submenu-animation-wrapper"
+      );
+      if (!wrapper) {
+        return;
+      }
+      wrapper.removeAttribute("mobile-transition");
+      requestAnimationFrame(() => {
+        wrapper.setAttribute("mobile-transition", direction);
+      });
+    });
+  }
+  /**
+   * Restores every projected submenu back to its original parent and
+   * clears the submenu stack. Called during `disconnectedCallback` or
+   * when the menu overlay closes to ensure a clean state.
+   */
+  resetMobileSubmenus() {
+    for (let i = this._mobileSubmenuStack.length - 1; i >= 0; i--) {
+      this._restoreMobileSubmenu(this._mobileSubmenuStack[i]);
+    }
+    this._mobileSubmenuStack = [];
+  }
+  /**
+   * Moves the submenu element from its MenuItem parent into this Menu's
+   * light DOM with a `mobile-submenu` slot, so it projects through the
+   * named slot in the shadow DOM. Any previously visible projected submenu
+   * is moved to a non-rendered slot to avoid both showing at once.
+   */
+  _projectMobileSubmenu(item) {
+    var _a;
+    const submenuEl = item.submenuElement;
+    if (!submenuEl) {
+      return;
+    }
+    const currentlyVisible = (_a = this.currentMobileSubmenu) == null ? void 0 : _a.submenuElement;
+    if (currentlyVisible) {
+      currentlyVisible.setAttribute("slot", "mobile-submenu-stacked");
+    }
+    const parentElement = submenuEl.parentElement;
+    if (!parentElement) {
+      return;
+    }
+    item._mobileSubmenuProjected = true;
+    this._mobileSubmenuOriginalParents.set(submenuEl, parentElement);
+    const submenu = this.asMenu(submenuEl);
+    const savedChildItems = new Set(submenu.childItemSet);
+    submenuEl.setAttribute("slot", "mobile-submenu");
+    this.appendChild(submenuEl);
+    this._restoreSubmenuChildState(submenu, savedChildItems);
+    this._renderMobileBackElements(submenuEl);
+  }
+  /**
+   * Restores the submenu element back to its original MenuItem parent
+   * and resets the slot attribute.
+   */
+  _restoreMobileSubmenu(item) {
+    const submenuEl = item.submenuElement;
+    if (!submenuEl) {
+      return;
+    }
+    this._removeMobileBackElements(submenuEl);
+    const submenu = this.asMenu(submenuEl);
+    const originalParent = this._mobileSubmenuOriginalParents.get(submenuEl);
+    if (originalParent) {
+      const savedChildItems = new Set(submenu.childItemSet);
+      submenuEl.setAttribute("slot", "submenu");
+      originalParent.appendChild(submenuEl);
+      this._mobileSubmenuOriginalParents.delete(submenuEl);
+      this._restoreSubmenuChildState(submenu, savedChildItems);
+    }
+    item._mobileSubmenuProjected = false;
+  }
+  /**
+   * Declaratively renders the mobile back button and divider into the
+   * projected submenu element using Lit's `render()`, so the back button
+   * lives inside the same `<sp-menu>` and participates in its
+   * `RovingTabindexController` for keyboard navigation. Re-renders
+   * whenever `dir` or `mobileBackLabel` change so the icon orientation
+   * and label stay in sync.
+   */
+  _renderMobileBackElements(submenuEl) {
+    var _a;
+    this._removeMobileBackElements(submenuEl);
+    const container = document.createElement("div");
+    container.className = "mobile-back-container";
+    submenuEl.insertBefore(container, submenuEl.firstChild);
+    this._mobileBackContainers.set(submenuEl, container);
+    render(
+      html`
+        <sp-menu-item
+          class="mobile-back-button"
+          data-mobile-back
+          @click=${this.handleMobileBackClick}
+        >
+          <sp-icon-arrow500
+            slot="icon"
+            class="mobile-back-icon"
+          ></sp-icon-arrow500>
+          ${this.mobileBackLabel}
+        </sp-menu-item>
+        <sp-menu-divider data-mobile-back></sp-menu-divider>
+      `,
+      container
+    );
+    const submenu = this.asMenu(submenuEl);
+    const backItem = submenuEl.querySelector(
+      ".mobile-back-button"
+    );
+    if (backItem) {
+      submenu.childItemSet.add(backItem);
+    }
+    submenu.cachedChildItems = void 0;
+    (_a = submenu.rovingTabindexController) == null ? void 0 : _a.clearElementCache();
+    if (submenu.rovingTabindexController) {
+      submenu.rovingTabindexController.currentIndex = 0;
+    }
+  }
+  /**
+   * Re-render any open mobile back containers so changes to
+   * `mobileBackLabel` (and other reactive values consumed by the
+   * back-button template) propagate without needing to close
+   * and re-open the drill-down.
+   */
+  _refreshMobileBackElements() {
+    this._mobileBackContainers.forEach((_container, submenuEl) => {
+      this._renderMobileBackElements(submenuEl);
+    });
+  }
+  /**
+   * Removes the mobile back button render container from the given
+   * projected submenu element.
+   */
+  _removeMobileBackElements(submenuEl) {
+    var _a;
+    const container = this._mobileBackContainers.get(submenuEl);
+    if (container) {
+      const backItem = submenuEl.querySelector(
+        ".mobile-back-button"
+      );
+      if (backItem) {
+        this.asMenu(submenuEl).childItemSet.delete(backItem);
+      }
+      container.remove();
+      this._mobileBackContainers.delete(submenuEl);
+      const submenu = this.asMenu(submenuEl);
+      submenu.cachedChildItems = void 0;
+      (_a = submenu.rovingTabindexController) == null ? void 0 : _a.clearElementCache();
+      if (submenu.rovingTabindexController) {
+        submenu.rovingTabindexController.currentIndex = 0;
+      }
+    }
+  }
+  /**
+   * Re-adds saved child items to the submenu's `childItemSet` and
+   * invalidates cached references after DOM re-parenting, so the
+   * `RovingTabindexController` picks up the correct set of focusable
+   * children.
+   *
+   * @param submenu - The submenu whose child state needs restoring.
+   * @param savedChildItems - The set of MenuItem children captured
+   *   before the DOM move.
+   */
+  _restoreSubmenuChildState(submenu, savedChildItems) {
+    var _a;
+    savedChildItems.forEach((child) => submenu.childItemSet.add(child));
+    submenu.cachedChildItems = void 0;
+    (_a = submenu.rovingTabindexController) == null ? void 0 : _a.clearElementCache();
+  }
   get selected() {
     return !this.selects ? [] : this._selected;
   }
@@ -615,6 +1027,33 @@ export class Menu extends SizedMixin(SpectrumElement, { noDefaultSize: true }) {
     const shouldOpenSubmenu = dir === "ltr" && key === "ArrowRight" || dir === "rtl" && key === "ArrowLeft";
     const shouldCloseSelfAsSubmenu = dir === "ltr" && key === "ArrowLeft" || dir === "rtl" && key === "ArrowRight" || key === "Escape";
     const lastFocusedItem = root;
+    if (this.mobileView) {
+      if (shouldOpenSubmenu && (lastFocusedItem == null ? void 0 : lastFocusedItem.hasSubmenu)) {
+        event.stopPropagation();
+        this.openMobileSubmenu(lastFocusedItem);
+        return;
+      }
+      if (shouldCloseSelfAsSubmenu && this._mobileSubmenuStack.length > 0) {
+        event.stopPropagation();
+        this.closeMobileSubmenu();
+        return;
+      }
+      return;
+    }
+    const mobileRoot = this._mobileViewRoot;
+    if (mobileRoot) {
+      if (shouldOpenSubmenu && (lastFocusedItem == null ? void 0 : lastFocusedItem.hasSubmenu)) {
+        event.stopPropagation();
+        mobileRoot.openMobileSubmenu(lastFocusedItem);
+        return;
+      }
+      if (shouldCloseSelfAsSubmenu) {
+        event.stopPropagation();
+        mobileRoot.closeMobileSubmenu();
+        return;
+      }
+      return;
+    }
     if (shouldOpenSubmenu) {
       if (lastFocusedItem == null ? void 0 : lastFocusedItem.hasSubmenu) {
         event.stopPropagation();
@@ -631,6 +1070,17 @@ export class Menu extends SizedMixin(SpectrumElement, { noDefaultSize: true }) {
     if (event.defaultPrevented || !this.rovingTabindexController) {
       return;
     }
+    if (this.mobileView && this._mobileSubmenuStack.length > 0) {
+      const { key: key2 } = event;
+      const dir = this.dir;
+      const shouldClose = dir === "ltr" && key2 === "ArrowLeft" || dir === "rtl" && key2 === "ArrowRight" || key2 === "Escape";
+      if (shouldClose) {
+        event.stopPropagation();
+        event.preventDefault();
+        this.closeMobileSubmenu();
+      }
+      return;
+    }
     const { key, root, shiftKey, target } = event;
     const openSubmenuKey = ["Enter", " "].includes(key);
     if (shiftKey && target !== this && this.hasAttribute("tabindex")) {
@@ -650,7 +1100,14 @@ export class Menu extends SizedMixin(SpectrumElement, { noDefaultSize: true }) {
     }
     if (openSubmenuKey && (root == null ? void 0 : root.hasSubmenu) && !root.open) {
       event.preventDefault();
-      root.openOverlay(true);
+      const mobileRoot = this._mobileViewRoot;
+      if (this.mobileView) {
+        this.openMobileSubmenu(root);
+      } else if (mobileRoot) {
+        mobileRoot.openMobileSubmenu(root);
+      } else {
+        root.openOverlay(true);
+      }
       return;
     }
     if (key === " " || key === "Enter") {
@@ -754,8 +1211,8 @@ export class Menu extends SizedMixin(SpectrumElement, { noDefaultSize: true }) {
       assignedElements.forEach((item) => {
         if (typeof item.triggerUpdate !== "undefined") {
           item.triggerUpdate();
-        } else if (typeof item.childItems !== "undefined") {
-          item.childItems.forEach((child) => {
+        } else if (typeof this.asMenu(item).childItems !== "undefined") {
+          this.asMenu(item).childItems.forEach((child) => {
             child.triggerUpdate();
           });
         }
@@ -776,7 +1233,22 @@ export class Menu extends SizedMixin(SpectrumElement, { noDefaultSize: true }) {
     `;
   }
   render() {
-    return this.renderMenuItemSlot();
+    const hasMobileSubmenu = this.mobileView && this._mobileSubmenuStack.length > 0;
+    return html`
+      <div
+        class=${hasMobileSubmenu ? "mobile-slot-hidden" : "mobile-slot-wrapper"}
+      >
+        ${this.renderMenuItemSlot()}
+      </div>
+      ${hasMobileSubmenu ? html`
+            <div
+              class="mobile-submenu-animation-wrapper"
+              @animationend=${this._handleAnimationEnd}
+            >
+              <slot name="mobile-submenu"></slot>
+            </div>
+          ` : ""}
+    `;
   }
   firstUpdated(changed) {
     super.firstUpdated(changed);
@@ -802,6 +1274,14 @@ export class Menu extends SizedMixin(SpectrumElement, { noDefaultSize: true }) {
         this.removeAttribute("aria-label");
       }
     }
+    if (changes.has("mobileBackLabel") && this.hasUpdated) {
+      this._refreshMobileBackElements();
+    }
+    if (changes.has("mobileView") && this.hasUpdated) {
+      if (!this.mobileView && this._mobileSubmenuStack.length > 0) {
+        this.resetMobileSubmenus();
+      }
+    }
   }
   selectsChanged() {
     const updates = [
@@ -828,6 +1308,8 @@ export class Menu extends SizedMixin(SpectrumElement, { noDefaultSize: true }) {
     this.selectedItemsMap.clear();
     this.childItemSet.clear();
     this.descendentOverlays = /* @__PURE__ */ new Map();
+    this.resetMobileSubmenus();
+    this._mobileSubmenuOriginalParents.clear();
     super.disconnectedCallback();
   }
   async getUpdateComplete() {
@@ -847,6 +1329,15 @@ __decorateClass([
 __decorateClass([
   property({ type: Boolean, reflect: true })
 ], Menu.prototype, "ignore", 2);
+__decorateClass([
+  property({ type: Boolean, attribute: "mobile-view", reflect: true })
+], Menu.prototype, "mobileView", 2);
+__decorateClass([
+  property({ type: String, attribute: "mobile-back-label" })
+], Menu.prototype, "mobileBackLabel", 2);
+__decorateClass([
+  state()
+], Menu.prototype, "_mobileSubmenuStack", 2);
 __decorateClass([
   property({ type: String, reflect: true })
 ], Menu.prototype, "selects", 2);