@vaadin/context-menu 25.0.0-alpha2 → 25.0.0-alpha20

package/src/vaadin-context-menu.d.ts

@@ -4,13 +4,26 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import type { ElementMixinClass } from '@vaadin/component-base/src/element-mixin.js';
-import type { OverlayClassMixinClass } from '@vaadin/component-base/src/overlay-class-mixin.js';
 import type { ThemePropertyMixinClass } from '@vaadin/vaadin-themable-mixin/vaadin-theme-property-mixin.js';
 import type { ContextMenuMixinClass } from './vaadin-context-menu-mixin.js';
 import type { ContextMenuItem } from './vaadin-contextmenu-items-mixin.js';
 
 export { ContextMenuItem };
 
+export type ContextMenuPosition =
+  | 'bottom-end'
+  | 'bottom-start'
+  | 'bottom'
+  | 'end-bottom'
+  | 'end-top'
+  | 'end'
+  | 'start-bottom'
+  | 'start-top'
+  | 'start'
+  | 'top-end'
+  | 'top-start'
+  | 'top';
+
 export interface ContextMenuRendererContext {
   target: HTMLElement;
   detail?: { sourceEvent: Event };
@@ -34,6 +47,11 @@ export type ContextMenuItemSelectedEvent<TItem extends ContextMenuItem = Context
   value: TItem;
 }>;
 
+/**
+ * Fired when the context menu is closed.
+ */
+export type ContextMenuClosedEvent = CustomEvent;
+
 export interface ContextMenuCustomEventMap<TItem extends ContextMenuItem = ContextMenuItem> {
   'opened-changed': ContextMenuOpenedChangedEvent;
 
@@ -42,6 +60,8 @@ export interface ContextMenuCustomEventMap<TItem extends ContextMenuItem = Conte
   'close-all-menus': Event;
 
   'items-outside-click': Event;
+
+  closed: ContextMenuClosedEvent;
 }
 
 export interface ContextMenuEventMap<TItem extends ContextMenuItem = ContextMenuItem>
@@ -208,18 +228,30 @@ export interface ContextMenuEventMap<TItem extends ContextMenuItem = ContextMenu
  *
  * ### Styling
  *
- * `<vaadin-context-menu>` uses `<vaadin-context-menu-overlay>` internal
- * themable component as the actual visible context menu overlay.
+ * The following shadow DOM parts are available for styling:
  *
- * See [`<vaadin-overlay>`](#/elements/vaadin-overlay)
- * documentation for `<vaadin-context-menu-overlay>` stylable parts.
+ * Part name        | Description
+ * -----------------|-------------------------------------------
+ * `backdrop`       | Backdrop of the overlay
+ * `overlay`        | The overlay container
+ * `content`        | The overlay content
+ *
+ * ### Custom CSS Properties
+ *
+ * The following custom CSS properties are available for styling:
+ *
+ * Custom CSS property                   | Description
+ * --------------------------------------|-------------
+ * `--vaadin-context-menu-offset-top`    | Used as an offset when using `position` and the context menu is aligned vertically below the target
+ * `--vaadin-context-menu-offset-bottom` | Used as an offset when using `position` and the context menu is aligned vertically above the target
+ * `--vaadin-context-menu-offset-start`  | Used as an offset when using `position` and the context menu is aligned horizontally after the target
+ * `--vaadin-context-menu-offset-end`    | Used as an offset when using `position` and the context menu is aligned horizontally before the target
  *
  * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  *
  * ### Internal components
  *
- * When using `items` API, in addition `<vaadin-context-menu-overlay>`, the following
- * internal components are themable:
+ * When using `items` API the following internal components are themable:
  *
  * - `<vaadin-context-menu-item>` - has the same API as [`<vaadin-item>`](#/elements/vaadin-item).
  * - `<vaadin-context-menu-list-box>` - has the same API as [`<vaadin-list-box>`](#/elements/vaadin-list-box).
@@ -231,13 +263,19 @@ export interface ContextMenuEventMap<TItem extends ContextMenuItem = ContextMenu
  * ---------- |-------------
  * `expanded` | Expanded parent item.
  *
- * Note: the `theme` attribute value set on `<vaadin-context-menu>` is
- * propagated to the internal components listed above.
- *
  * @fires {CustomEvent} opened-changed - Fired when the `opened` property changes.
  * @fires {CustomEvent} item-selected - Fired when an item is selected when the context menu is populated using the `items` API.
+ * @fires {CustomEvent} closed - Fired when the context menu is closed.
  */
 declare class ContextMenu<TItem extends ContextMenuItem = ContextMenuItem> extends HTMLElement {
+  /**
+   * Position of the overlay with respect to the target.
+   * Supported values: null, `top-start`, `top`, `top-end`,
+   * `bottom-start`, `bottom`, `bottom-end`, `start-top`,
+   * `start`, `start-bottom`, `end-top`, `end`, `end-bottom`.
+   */
+  position: ContextMenuPosition | null | undefined;
+
   addEventListener<K extends keyof ContextMenuEventMap>(
     type: K,
     listener: (this: ContextMenu<TItem>, ev: ContextMenuEventMap<TItem>[K]) => void,
@@ -253,7 +291,6 @@ declare class ContextMenu<TItem extends ContextMenuItem = ContextMenuItem> exten
 
 interface ContextMenu<TItem extends ContextMenuItem = ContextMenuItem>
   extends ContextMenuMixinClass<TItem>,
-    OverlayClassMixinClass,
     ElementMixinClass,
     ThemePropertyMixinClass {}
 

package/src/vaadin-context-menu.js

@@ -8,9 +8,9 @@ import './vaadin-context-menu-item.js';
 import './vaadin-context-menu-list-box.js';
 import './vaadin-context-menu-overlay.js';
 import { css, html, LitElement } from 'lit';
+import { ifDefined } from 'lit/directives/if-defined.js';
 import { defineCustomElement } from '@vaadin/component-base/src/define.js';
 import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
-import { OverlayClassMixin } from '@vaadin/component-base/src/overlay-class-mixin.js';
 import { PolylitMixin } from '@vaadin/component-base/src/polylit-mixin.js';
 import { ThemePropertyMixin } from '@vaadin/vaadin-themable-mixin/vaadin-theme-property-mixin.js';
 import { ContextMenuMixin } from './vaadin-context-menu-mixin.js';
@@ -175,18 +175,30 @@ import { ContextMenuMixin } from './vaadin-context-menu-mixin.js';
  *
  * ### Styling
  *
- * `<vaadin-context-menu>` uses `<vaadin-context-menu-overlay>` internal
- * themable component as the actual visible context menu overlay.
+ * The following shadow DOM parts are available for styling:
  *
- * See [`<vaadin-overlay>`](#/elements/vaadin-overlay)
- * documentation for `<vaadin-context-menu-overlay>` stylable parts.
+ * Part name        | Description
+ * -----------------|-------------------------------------------
+ * `backdrop`       | Backdrop of the overlay
+ * `overlay`        | The overlay container
+ * `content`        | The overlay content
+ *
+ * ### Custom CSS Properties
+ *
+ * The following custom CSS properties are available for styling:
+ *
+ * Custom CSS property                   | Description
+ * --------------------------------------|-------------
+ * `--vaadin-context-menu-offset-top`    | Used as an offset when using `position` and the context menu is aligned vertically below the target
+ * `--vaadin-context-menu-offset-bottom` | Used as an offset when using `position` and the context menu is aligned vertically above the target
+ * `--vaadin-context-menu-offset-start`  | Used as an offset when using `position` and the context menu is aligned horizontally after the target
+ * `--vaadin-context-menu-offset-end`    | Used as an offset when using `position` and the context menu is aligned horizontally before the target
  *
  * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  *
  * ### Internal components
  *
- * When using `items` API, in addition `<vaadin-context-menu-overlay>`, the following
- * internal components are themable:
+ * When using `items` API the following internal components are themable:
  *
  * - `<vaadin-context-menu-item>` - has the same API as [`<vaadin-item>`](#/elements/vaadin-item).
  * - `<vaadin-context-menu-list-box>` - has the same API as [`<vaadin-list-box>`](#/elements/vaadin-list-box).
@@ -198,22 +210,17 @@ import { ContextMenuMixin } from './vaadin-context-menu-mixin.js';
  * ---------- |-------------
  * `expanded` | Expanded parent item.
  *
- * Note: the `theme` attribute value set on `<vaadin-context-menu>` is
- * propagated to the internal components listed above.
- *
  * @fires {CustomEvent} opened-changed - Fired when the `opened` property changes.
  * @fires {CustomEvent} item-selected - Fired when an item is selected when the context menu is populated using the `items` API.
+ * @fires {CustomEvent} closed - Fired when the context menu is closed.
  *
  * @customElement
  * @extends HTMLElement
  * @mixes ElementMixin
  * @mixes ContextMenuMixin
- * @mixes OverlayClassMixin
  * @mixes ThemePropertyMixin
  */
-class ContextMenu extends ContextMenuMixin(
-  OverlayClassMixin(ElementMixin(ThemePropertyMixin(PolylitMixin(LitElement)))),
-) {
+class ContextMenu extends ContextMenuMixin(ElementMixin(ThemePropertyMixin(PolylitMixin(LitElement)))) {
   static get is() {
     return 'vaadin-context-menu';
   }
@@ -230,19 +237,87 @@ class ContextMenu extends ContextMenuMixin(
     `;
   }
 
+  static get properties() {
+    return {
+      /**
+       * Position of the overlay with respect to the target.
+       * Supported values: null, `top-start`, `top`, `top-end`,
+       * `bottom-start`, `bottom`, `bottom-end`, `start-top`,
+       * `start`, `start-bottom`, `end-top`, `end`, `end-bottom`.
+       */
+      position: {
+        type: String,
+      },
+    };
+  }
+
   /** @protected */
   render() {
-    return html`<slot id="slot"></slot>`;
+    const { _context: context, position } = this;
+
+    return html`
+      <slot id="slot"></slot>
+      <vaadin-context-menu-overlay
+        id="overlay"
+        .owner="${this}"
+        .opened="${this.opened}"
+        .model="${context}"
+        .modeless="${this._modeless}"
+        .renderer="${this.items ? this.__itemsRenderer : this.renderer}"
+        .position="${position}"
+        .positionTarget="${position ? context && context.target : this._positionTarget}"
+        .horizontalAlign="${this.__computeHorizontalAlign(position)}"
+        .verticalAlign="${this.__computeVerticalAlign(position)}"
+        ?no-horizontal-overlap="${this.__computeNoHorizontalOverlap(position)}"
+        ?no-vertical-overlap="${this.__computeNoVerticalOverlap(position)}"
+        .withBackdrop="${this._phone}"
+        ?phone="${this._phone}"
+        theme="${ifDefined(this._theme)}"
+        exportparts="backdrop, overlay, content"
+        @opened-changed="${this._onOverlayOpened}"
+        @vaadin-overlay-open="${this._onVaadinOverlayOpen}"
+        @vaadin-overlay-closed="${this._onVaadinOverlayClosed}"
+      >
+        <slot name="overlay"></slot>
+        <slot name="submenu" slot="submenu"></slot>
+      </vaadin-context-menu-overlay>
+    `;
   }
 
-  /**
-   * @protected
-   * @override
-   */
-  createRenderRoot() {
-    const root = super.createRenderRoot();
-    root.appendChild(this._overlayElement);
-    return root;
+  /** @private */
+  __computeHorizontalAlign(position) {
+    if (!position) {
+      return 'start';
+    }
+
+    return ['top-end', 'bottom-end', 'start-top', 'start', 'start-bottom'].includes(position) ? 'end' : 'start';
+  }
+
+  /** @private */
+  __computeNoHorizontalOverlap(position) {
+    if (!position) {
+      return !!this._positionTarget;
+    }
+
+    return ['start-top', 'start', 'start-bottom', 'end-top', 'end', 'end-bottom'].includes(position);
+  }
+
+  /** @private */
+  __computeNoVerticalOverlap(position) {
+    if (!position) {
+      return false;
+    }
+
+    return ['top-start', 'top-end', 'top', 'bottom-start', 'bottom', 'bottom-end'].includes(position);
+  }
+
+  /** @private */
+  __computeVerticalAlign(position) {
+    if (!position) {
+      return 'top';
+    }
+
+    return ['top-start', 'top-end', 'top', 'start-bottom', 'end-bottom'].includes(position) ? 'bottom' : 'top';
   }
 
   /**

package/src/vaadin-contextmenu-items-mixin.js

@@ -16,14 +16,14 @@ export const ItemsMixin = (superClass) =>
          * @typedef ContextMenuItem
          * @type {object}
          * @property {string} text - Text to be set as the menu item component's textContent
-         * @property {union: string | object} component - The component to represent the item.
+         * @property {string | HTMLElement} component - The component to represent the item.
          * Either a tagName or an element instance. Defaults to "vaadin-context-menu-item".
          * @property {boolean} disabled - If true, the item is disabled and cannot be selected
          * @property {boolean} checked - If true, the item shows a checkmark next to it
          * @property {boolean} keepOpen - If true, the menu will not be closed on item selection
          * @property {string} className - A space-delimited list of CSS class names to be set on the menu item component.
-         * @property {union: string | string[]} theme - If set, sets the given theme(s) as an attribute to the menu item component, overriding any theme set on the context menu.
-         * @property {MenuItem[]} children - Array of child menu items
+         * @property {string | string[]} theme - If set, sets the given theme(s) as an attribute to the menu item component, overriding any theme set on the context menu.
+         * @property {ContextMenuItem[]} children - Array of child menu items
          */
 
         /**
@@ -60,6 +60,12 @@ export const ItemsMixin = (superClass) =>
           type: Array,
           sync: true,
         },
+
+        /** @protected */
+        _positionTarget: {
+          type: Object,
+          sync: true,
+        },
       };
     }
 
@@ -116,10 +122,10 @@ export const ItemsMixin = (superClass) =>
     /** @protected */
     __forwardFocus() {
       const overlay = this._overlayElement;
-      const child = overlay.getFirstChild();
+      const child = overlay._contentRoot.firstElementChild;
       // If parent item is not focused, do not focus submenu
       if (overlay.parentOverlay) {
-        const parent = overlay.parentOverlay.querySelector('[expanded]');
+        const parent = overlay.parentOverlay._contentRoot.querySelector('[expanded]');
         if (parent && parent.hasAttribute('focused') && child) {
           child.focus();
         } else {
@@ -131,16 +137,12 @@ export const ItemsMixin = (superClass) =>
     }
 
     /** @private */
-    __openSubMenu(subMenu, itemElement, overlayClass) {
-      subMenu.items = itemElement._item.children;
-      subMenu.listenOn = itemElement;
-      subMenu.overlayClass = overlayClass;
+    __openSubMenu(subMenu, itemElement) {
+      // Update sub-menu items and position target
+      this.__updateSubMenuForItem(subMenu, itemElement);
 
       const parent = this._overlayElement;
-
       const subMenuOverlay = subMenu._overlayElement;
-      subMenuOverlay.positionTarget = itemElement;
-      subMenuOverlay.noHorizontalOverlap = true;
       // Store the reference parent overlay
       subMenuOverlay._setParentOverlay(parent);
 
@@ -163,6 +165,14 @@ export const ItemsMixin = (superClass) =>
       );
     }
 
+    /** @private */
+    __updateSubMenuForItem(subMenu, itemElement) {
+      subMenu.items = itemElement._item.children;
+      subMenu.listenOn = itemElement;
+      subMenu._positionTarget = itemElement;
+      subMenu._overlayElement.requestContentUpdate();
+    }
+
     /**
      * @param {!ContextMenuItem} item
      * @return {HTMLElement}
@@ -248,10 +258,20 @@ export const ItemsMixin = (superClass) =>
       // Open a submenu on click event when a touch device is used.
       // On desktop, a submenu opens on hover.
       overlay.addEventListener(isTouch ? 'click' : 'mouseover', (event) => {
+        // Ignore events from the submenus
+        if (event.composedPath().includes(this._subMenu)) {
+          return;
+        }
+
         this.__showSubMenu(event);
       });
 
       overlay.addEventListener('keydown', (event) => {
+        // Ignore events from the submenus
+        if (event.composedPath().includes(this._subMenu)) {
+          return;
+        }
+
         const { key } = event;
         const isRTL = this.__isRTL;
 
@@ -283,10 +303,6 @@ export const ItemsMixin = (superClass) =>
       subMenu._modeless = true;
       subMenu.openOn = 'opensubmenu';
 
-      // Sub-menu doesn't have a target to wrap,
-      // so there is no need to keep it visible.
-      subMenu.setAttribute('hidden', '');
-
       // Close sub-menu when the parent menu closes.
       this.addEventListener('opened-changed', (event) => {
         if (!event.detail.value) {
@@ -317,14 +333,10 @@ export const ItemsMixin = (superClass) =>
         const menu = e.target;
         const selectedItem = e.detail.value;
         const index = menu.items.indexOf(selectedItem);
-        if (!!selectedItem.keepOpen && index > -1) {
-          menu._overlayElement.requestContentUpdate();
-
-          // Initialize items synchronously
-          menu._listBox._observer.flush();
-
-          const newItem = menu._listBox.children[index];
-          newItem.focus();
+        // Menu can be no longer opened if parent menu items changed
+        if (!!selectedItem.keepOpen && index > -1 && menu.opened) {
+          menu.__selectedIndex = index;
+          menu.requestContentUpdate();
         } else if (!selectedItem.keepOpen) {
           this.close();
         }
@@ -360,27 +372,33 @@ export const ItemsMixin = (superClass) =>
       }
 
       const subMenu = this._subMenu;
+      const expandedItem = this._listBox.querySelector('[expanded]');
 
-      if (item) {
+      if (item && item !== expandedItem) {
         const { children } = item._item;
 
         // Check if the sub-menu was focused before closing it.
-        const child = subMenu._overlayElement.getFirstChild();
+        const child = subMenu._overlayElement._contentRoot.firstElementChild;
         const isSubmenuFocused = child && child.focused;
 
-        if (subMenu.items !== children) {
+        // Mark previously expanded item as collapsed
+        if (expandedItem) {
+          this.__updateExpanded(expandedItem, false);
+        }
+
+        // Close sub-menu if there are no children for the new item
+        if (!children || !children.length) {
           subMenu.close();
         }
+
         if (!this.opened) {
           return;
         }
 
         if (children && children.length) {
+          // Open or update the submenu if the new item has children
           this.__updateExpanded(item, true);
-
-          // Forward parent overlay class
-          const { overlayClass } = this;
-          this.__openSubMenu(subMenu, item, overlayClass);
+          this.__openSubMenu(subMenu, item);
         } else if (isSubmenuFocused) {
           // If the sub-menu item was focused, focus its parent item.
           subMenu.listenOn.focus();
@@ -391,24 +409,25 @@ export const ItemsMixin = (superClass) =>
       }
     }
 
+    /** @protected */
+    __getListBox() {
+      return this._overlayElement._contentRoot.querySelector(`${this._tagNamePrefix}-list-box`);
+    }
+
     /**
      * @param {!HTMLElement} root
      * @param {!ContextMenu} menu
-     * @param {!ContextMenuRendererContext} context
      * @protected
      */
-    __itemsRenderer(root, menu, { detail }) {
+    __itemsRenderer(root, menu) {
       this.__initMenu(root, menu);
 
-      const subMenu = root.querySelector(this.constructor.is);
-      subMenu.closeOn = menu.closeOn;
-
-      const listBox = root.querySelector(`${this._tagNamePrefix}-list-box`);
-      listBox.innerHTML = '';
+      this._subMenu.closeOn = menu.closeOn;
+      this._listBox.innerHTML = '';
 
-      [...(detail.children || menu.items)].forEach((item) => {
+      menu.items.forEach((item) => {
         const component = this.__createComponent(item);
-        listBox.appendChild(component);
+        this._listBox.appendChild(component);
       });
     }
 
@@ -449,8 +468,9 @@ export const ItemsMixin = (superClass) =>
         root.appendChild(listBox);
 
         const subMenu = this.__initSubMenu();
+        subMenu.slot = 'submenu';
         this._subMenu = subMenu;
-        root.appendChild(subMenu);
+        this.appendChild(subMenu);
 
         requestAnimationFrame(() => {
           this.__openListenerActive = true;

package/src/vaadin-menu-overlay-mixin.d.ts

@@ -18,9 +18,4 @@ export declare class MenuOverlayMixinClass {
    * Returns the adjusted boundaries of the overlay.
    */
   getBoundaries(): { xMax: number; xMin: number; yMax: number };
-
-  /**
-   * Returns the first element in the overlay content.
-   */
-  getFirstChild(): HTMLElement;
 }

package/src/vaadin-menu-overlay-mixin.js

@@ -3,7 +3,6 @@
  * Copyright (c) 2016 - 2025 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import { getClosestElement } from '@vaadin/component-base/src/dom-utils.js';
 import { OverlayFocusMixin } from '@vaadin/overlay/src/vaadin-overlay-focus-mixin.js';
 import { PositionMixin } from '@vaadin/overlay/src/vaadin-overlay-position-mixin.js';
 
@@ -37,6 +36,23 @@ export const MenuOverlayMixin = (superClass) =>
       return ['_themeChanged(_theme)'];
     }
 
+    /**
+     * Override method from OverlayFocusMixin to use slotted div as the content root.
+     * @protected
+     * @override
+     */
+    get _contentRoot() {
+      if (!this.__savedRoot) {
+        const root = document.createElement('div');
+        root.setAttribute('slot', 'overlay');
+        root.style.display = 'contents';
+        this.owner.appendChild(root);
+        this.__savedRoot = root;
+      }
+
+      return this.__savedRoot;
+    }
+
     /** @protected */
     ready() {
       super.ready();
@@ -45,7 +61,7 @@ export const MenuOverlayMixin = (superClass) =>
 
       this.addEventListener('keydown', (e) => {
         if (!e.defaultPrevented && e.composedPath()[0] === this.$.overlay && [38, 40].indexOf(e.keyCode) > -1) {
-          const child = this.getFirstChild();
+          const child = this._contentRoot.firstElementChild;
           if (child && Array.isArray(child.items) && child.items.length) {
             e.preventDefault();
             if (e.keyCode === 38) {
@@ -58,15 +74,6 @@ export const MenuOverlayMixin = (superClass) =>
       });
     }
 
-    /**
-     * Returns the first element in the overlay content.
-     *
-     * @returns {HTMLElement}
-     */
-    getFirstChild() {
-      return this.querySelector(':not(style):not(slot)');
-    }
-
     /** @private */
     _themeChanged() {
       this.close();
@@ -106,7 +113,7 @@ export const MenuOverlayMixin = (superClass) =>
     _updatePosition() {
       super._updatePosition();
 
-      if (this.positionTarget && this.parentOverlay) {
+      if (this.positionTarget && this.parentOverlay && this.opened) {
         // This overlay is positioned by a parent menu item,
         // adjust the position by the overlay content paddings
         const content = this.$.content;
@@ -149,9 +156,9 @@ export const MenuOverlayMixin = (superClass) =>
     }
 
     /**
-     * Override method inherited from `OverlayFocusMixin` to return
-     * true if the overlay contains the given node, including
-     * those within descendant menu overlays.
+     * Override method inherited from `OverlayFocusMixin` to check if the
+     * node is contained within the overlay's owner element (the menu),
+     * where all content (overlay content, sub-menus, etc.) is slotted.
      *
      * @protected
      * @override
@@ -159,18 +166,6 @@ export const MenuOverlayMixin = (superClass) =>
      * @return {boolean}
      */
     _deepContains(node) {
-      // Find the closest menu overlay for the given node.
-      let overlay = getClosestElement(this.localName, node);
-      while (overlay) {
-        if (overlay === this) {
-          // The node is inside a descendant menu overlay.
-          return true;
-        }
-
-        // Traverse the overlay hierarchy to check parent overlays.
-        overlay = overlay.parentOverlay;
-      }
-
-      return false;
+      return this.owner.contains(node);
     }
   };

package/vaadin-context-menu.js

@@ -1,2 +1,2 @@
-import './theme/lumo/vaadin-context-menu.js';
+import './src/vaadin-context-menu.js';
 export * from './src/vaadin-context-menu.js';