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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spectrum-web-components/menu",
-  "version": "1.12.0-testing.20260223092154",
+  "version": "1.12.0",
   "description": "",
   "license": "Apache-2.0",
   "author": "Adobe",
@@ -86,15 +86,15 @@
   "types": "./src/index.d.ts",
   "dependencies": {
     "@lit-labs/observers": "2.0.2",
-    "@spectrum-web-components/action-button": "1.12.0-testing.20260223092154",
-    "@spectrum-web-components/base": "1.12.0-testing.20260223092154",
-    "@spectrum-web-components/divider": "1.12.0-testing.20260223092154",
-    "@spectrum-web-components/icon": "1.12.0-testing.20260223092154",
-    "@spectrum-web-components/icons-ui": "1.12.0-testing.20260223092154",
-    "@spectrum-web-components/overlay": "1.12.0-testing.20260223092154",
-    "@spectrum-web-components/popover": "1.12.0-testing.20260223092154",
-    "@spectrum-web-components/reactive-controllers": "1.12.0-testing.20260223092154",
-    "@spectrum-web-components/shared": "1.12.0-testing.20260223092154"
+    "@spectrum-web-components/action-button": "1.12.0",
+    "@spectrum-web-components/base": "1.12.0",
+    "@spectrum-web-components/divider": "1.12.0",
+    "@spectrum-web-components/icon": "1.12.0",
+    "@spectrum-web-components/icons-ui": "1.12.0",
+    "@spectrum-web-components/overlay": "1.12.0",
+    "@spectrum-web-components/popover": "1.12.0",
+    "@spectrum-web-components/reactive-controllers": "1.12.0",
+    "@spectrum-web-components/shared": "1.12.0"
   },
   "keywords": [
     "design-system",

package/src/Menu.d.ts

@@ -11,6 +11,8 @@
  */
 import { CSSResultArray, PropertyValues, SpectrumElement, TemplateResult } from '@spectrum-web-components/base';
 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.js';
 import type { MenuItemKeydownEvent } from './MenuItem.js';
 import { MenuItem } from './MenuItem.js';
 export interface MenuChildItem {
@@ -20,10 +22,7 @@ export interface MenuChildItem {
     focusable: boolean;
     focusRoot: Menu;
 }
-declare const Menu_base: typeof SpectrumElement & {
-    new (...args: any[]): import("@spectrum-web-components/base").SizedElementInterface;
-    prototype: import("@spectrum-web-components/base").SizedElementInterface;
-} & import("@spectrum-web-components/core/mixins/sized-mixin.js").SizedElementConstructor;
+declare const Menu_base: typeof SpectrumElement & import("@spectrum-web-components/base").Constructor<import("@spectrum-web-components/base").SizedElementInterface> & import("@spectrum-web-components/base").SizedElementConstructor;
 /**
  * Spectrum Menu Component
  *
@@ -49,6 +48,8 @@ export declare class Menu extends Menu_base {
         slotAssignment?: SlotAssignmentMode;
     };
     private get isSubmenu();
+    private asMenu;
+    private get _mobileViewRoot();
     protected rovingTabindexController?: RovingTabindexController<MenuItem>;
     /**
      * iPad scroll detection properties
@@ -113,6 +114,148 @@ export declare class Menu extends Menu_base {
      */
     get isScrolling(): boolean;
     set isScrolling(value: boolean);
+    /**
+     * 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(): MenuItem | undefined;
+    /**
+     * 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: MenuItem): void;
+    /**
+     * 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(): void;
+    /**
+     * 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.
+     */
+    private _focusProjectedSubmenu;
+    /**
+     * 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.
+     */
+    private _focusMobileBackRow;
+    /**
+     * 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.
+     */
+    private _focusFirstItemInCurrentNestedSubmenu;
+    /**
+     * 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.
+     */
+    private handleMobileDrilldownKeydownCapture;
+    /**
+     * 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.
+     */
+    private _triggerMobileTransition;
+    /**
+     * 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.
+     */
+    private _handleAnimationEnd;
+    /**
+     * 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(): void;
+    /**
+     * 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.
+     */
+    private _projectMobileSubmenu;
+    /**
+     * Restores the submenu element back to its original MenuItem parent
+     * and resets the slot attribute.
+     */
+    private _restoreMobileSubmenu;
+    /**
+     * Handles click on the mobile back button. Stops the event from
+     * reaching parent menus and closes the current mobile submenu.
+     */
+    private handleMobileBackClick;
+    /**
+     * 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.
+     */
+    private _mobileBackContainers;
+    /**
+     * 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.
+     */
+    private _renderMobileBackElements;
+    /**
+     * 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.
+     */
+    private _refreshMobileBackElements;
+    /**
+     * Removes the mobile back button render container from the given
+     * projected submenu element.
+     */
+    private _removeMobileBackElements;
+    /**
+     * 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.
+     */
+    private _restoreSubmenuChildState;
+    /**
+     * Maps each projected submenu element to its original parent so the
+     * element can be moved back when the submenu is closed.
+     */
+    private _mobileSubmenuOriginalParents;
     /**
      * label of the menu
      */
@@ -121,6 +264,17 @@ export declare class Menu extends Menu_base {
      * whether menu should be ignored by roving tabindex controller
      */
     ignore: boolean;
+    /**
+     * Enables mobile submenu navigation where tapping a submenu item replaces
+     * the current menu content with the submenu's children (drill-down) instead
+     * of opening a flyout overlay.
+     */
+    mobileView: boolean;
+    /**
+     * Label for the mobile back button, used for localization.
+     */
+    mobileBackLabel: string;
+    private _mobileSubmenuStack;
     /**
      * how the menu allows selection of its items:
      * - `undefined` (default): no selection is allowed