@vaadin/context-menu 24.0.0-alpha8 → 24.0.0-beta1

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

@@ -3,37 +3,10 @@
  * Copyright (c) 2016 - 2023 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
+import './vaadin-context-menu-item.js';
+import './vaadin-context-menu-list-box.js';
 import { isTouch } from '@vaadin/component-base/src/browser-utils.js';
 import { Item } from '@vaadin/item/src/vaadin-item.js';
-import { ListBox } from '@vaadin/list-box/src/vaadin-list-box.js';
-
-/**
- * An element used internally by `<vaadin-context-menu>`. Not intended to be used separately.
- *
- * @extends Item
- * @protected
- */
-class ContextMenuItemElement extends Item {
-  static get is() {
-    return 'vaadin-context-menu-item';
-  }
-}
-
-customElements.define(ContextMenuItemElement.is, ContextMenuItemElement);
-
-/**
- * An element used internally by `<vaadin-context-menu>`. Not intended to be used separately.
- *
- * @extends ListBox
- * @protected
- */
-class ContextMenuListBox extends ListBox {
-  static get is() {
-    return 'vaadin-context-menu-list-box';
-  }
-}
-
-customElements.define(ContextMenuListBox.is, ContextMenuListBox);
 
 /**
  * @polymerMixin
@@ -65,20 +38,20 @@ export const ItemsMixin = (superClass) =>
          *
          * ```javascript
          * contextMenu.items = [
-         *   {text: 'Menu Item 1', theme: 'primary', children:
+         *   { text: 'Menu Item 1', theme: 'primary', children:
          *     [
-         *       {text: 'Menu Item 1-1', checked: true},
-         *       {text: 'Menu Item 1-2'}
+         *       { text: 'Menu Item 1-1', checked: true },
+         *       { text: 'Menu Item 1-2' }
          *     ]
          *   },
-         *   {component: 'hr'},
-         *   {text: 'Menu Item 2', children:
+         *   { component: 'hr' },
+         *   { text: 'Menu Item 2', children:
          *     [
-         *       {text: 'Menu Item 2-1'},
-         *       {text: 'Menu Item 2-2', disabled: true}
+         *       { text: 'Menu Item 2-1' },
+         *       { text: 'Menu Item 2-2', disabled: true }
          *     ]
          *   },
-         *   {text: 'Menu Item 3', disabled: true}
+         *   { text: 'Menu Item 3', disabled: true }
          * ];
          * ```
          *
@@ -98,6 +71,15 @@ export const ItemsMixin = (superClass) =>
       };
     }
 
+    /**
+     * Tag name prefix used by overlay, list-box and items.
+     * @protected
+     * @return {string}
+     */
+    get _tagNamePrefix() {
+      return 'vaadin-context-menu';
+    }
+
     /** @protected */
     ready() {
       super.ready();
@@ -105,7 +87,7 @@ export const ItemsMixin = (superClass) =>
       // Overlay's outside click listener doesn't work with modeless
       // overlays (submenus) so we need additional logic for it
       this.__itemsOutsideClickListener = (e) => {
-        if (!e.composedPath().some((el) => el.localName === 'vaadin-context-menu-overlay')) {
+        if (!e.composedPath().some((el) => el.localName === `${this._tagNamePrefix}-overlay`)) {
           this.dispatchEvent(new CustomEvent('items-outside-click'));
         }
       };
@@ -144,9 +126,10 @@ export const ItemsMixin = (superClass) =>
     }
 
     /** @private */
-    __openSubMenu(subMenu, itemElement) {
+    __openSubMenu(subMenu, itemElement, overlayClass) {
       subMenu.items = itemElement._item.children;
       subMenu.listenOn = itemElement;
+      subMenu.overlayClass = overlayClass;
 
       const parent = this.$.overlay;
 
@@ -187,7 +170,7 @@ export const ItemsMixin = (superClass) =>
       const subMenu = root.querySelector(this.constructor.is);
       subMenu.closeOn = menu.closeOn;
 
-      const listBox = root.querySelector('vaadin-context-menu-list-box');
+      const listBox = root.querySelector(`${this._tagNamePrefix}-list-box`);
 
       listBox.innerHTML = '';
 
@@ -198,7 +181,7 @@ export const ItemsMixin = (superClass) =>
         if (item.component instanceof HTMLElement) {
           component = item.component;
         } else {
-          component = document.createElement(item.component || 'vaadin-context-menu-item');
+          component = document.createElement(item.component || `${this._tagNamePrefix}-item`);
         }
 
         if (component instanceof Item) {
@@ -261,7 +244,7 @@ export const ItemsMixin = (superClass) =>
     /** @private */
     __initMenu(root, menu) {
       if (!root.firstElementChild) {
-        const listBox = document.createElement('vaadin-context-menu-list-box');
+        const listBox = document.createElement(`${this._tagNamePrefix}-list-box`);
         root.appendChild(listBox);
 
         if (this._theme) {
@@ -323,7 +306,7 @@ export const ItemsMixin = (superClass) =>
         });
         const openSubMenu = (
           e,
-          itemElement = e.composedPath().find((e) => e.localName === 'vaadin-context-menu-item'),
+          itemElement = e.composedPath().find((e) => e.localName === `${this._tagNamePrefix}-item`),
         ) => {
           // Delay enabling the mouseover listener to avoid it from triggering on parent menu open
           if (!this.__openListenerActive) {
@@ -346,7 +329,10 @@ export const ItemsMixin = (superClass) =>
             if (itemElement._item.children && itemElement._item.children.length) {
               itemElement.setAttribute('aria-expanded', 'true');
               itemElement.setAttribute('expanded', '');
-              this.__openSubMenu(subMenu, itemElement);
+
+              // Forward parent overlay class
+              const { overlayClass } = menu;
+              this.__openSubMenu(subMenu, itemElement, overlayClass);
             } else {
               subMenu.listenOn.focus();
             }
@@ -367,7 +353,7 @@ export const ItemsMixin = (superClass) =>
           }
         });
       } else {
-        const listBox = root.querySelector('vaadin-context-menu-list-box');
+        const listBox = root.querySelector(`${this._tagNamePrefix}-list-box`);
         if (this._theme) {
           listBox.setAttribute('theme', this._theme);
         } else {

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

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright (c) 2016 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import type { Constructor } from '@open-wc/dedupe-mixin';
+import type { PositionMixinClass } from '@vaadin/overlay/src/vaadin-overlay-position-mixin.js';
+
+export declare function MenuOverlayMixin<T extends Constructor<HTMLElement>>(
+  base: T,
+): Constructor<MenuOverlayMixinClass> & Constructor<PositionMixinClass> & T;
+
+export declare class MenuOverlayMixinClass {
+  protected readonly parentOverlay: HTMLElement | undefined;
+
+  /**
+   * 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

@@ -0,0 +1,119 @@
+/**
+ * @license
+ * Copyright (c) 2016 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { PositionMixin } from '@vaadin/overlay/src/vaadin-overlay-position-mixin.js';
+
+/**
+ * @polymerMixin
+ */
+export const MenuOverlayMixin = (superClass) =>
+  class MenuOverlayMixin extends PositionMixin(superClass) {
+    static get properties() {
+      return {
+        /**
+         * @protected
+         */
+        parentOverlay: {
+          type: Object,
+          readOnly: true,
+        },
+      };
+    }
+
+    static get observers() {
+      return ['_themeChanged(_theme)'];
+    }
+
+    /** @protected */
+    ready() {
+      super.ready();
+
+      this.addEventListener('keydown', (e) => {
+        if (!e.defaultPrevented && e.composedPath()[0] === this.$.overlay && [38, 40].indexOf(e.keyCode) > -1) {
+          const child = this.getFirstChild();
+          if (child && Array.isArray(child.items) && child.items.length) {
+            e.preventDefault();
+            if (e.keyCode === 38) {
+              child.items[child.items.length - 1].focus();
+            } else {
+              child.focus();
+            }
+          }
+        }
+      });
+    }
+
+    /**
+     * Returns the first element in the overlay content.
+     *
+     * @returns {HTMLElement}
+     */
+    getFirstChild() {
+      return this.querySelector(':not(style):not(slot)');
+    }
+
+    /** @private */
+    _themeChanged() {
+      this.close();
+    }
+
+    /**
+     * Returns the adjusted boundaries of the overlay.
+     *
+     * @returns {object}
+     */
+    getBoundaries() {
+      // Measure actual overlay and content sizes
+      const overlayRect = this.getBoundingClientRect();
+      const contentRect = this.$.overlay.getBoundingClientRect();
+
+      // Maximum x and y values are imposed by content size and overlay limits.
+      let yMax = overlayRect.bottom - contentRect.height;
+
+      // Adjust constraints to ensure bottom-aligned applies to sub-menu.
+      const parent = this.parentOverlay;
+      if (parent && parent.hasAttribute('bottom-aligned')) {
+        const parentStyle = getComputedStyle(parent);
+        yMax = yMax - parseFloat(parentStyle.bottom) - parseFloat(parentStyle.height);
+      }
+
+      return {
+        xMax: overlayRect.right - contentRect.width,
+        xMin: overlayRect.left + contentRect.width,
+        yMax,
+      };
+    }
+
+    /**
+     * @protected
+     * @override
+     */
+    _updatePosition() {
+      super._updatePosition();
+
+      if (this.positionTarget && this.parentOverlay) {
+        // This overlay is positioned by a parent menu item,
+        // adjust the position by the overlay content paddings
+        const content = this.$.content;
+        const style = getComputedStyle(content);
+
+        // Horizontal adjustment
+        const isLeftAligned = !!this.style.left;
+        if (isLeftAligned) {
+          this.style.left = `${parseFloat(this.style.left) + parseFloat(style.paddingLeft)}px`;
+        } else {
+          this.style.right = `${parseFloat(this.style.right) + parseFloat(style.paddingRight)}px`;
+        }
+
+        // Vertical adjustment
+        const isBottomAligned = !!this.style.bottom;
+        if (isBottomAligned) {
+          this.style.bottom = `${parseFloat(this.style.bottom) - parseFloat(style.paddingBottom)}px`;
+        } else {
+          this.style.top = `${parseFloat(this.style.top) - parseFloat(style.paddingTop)}px`;
+        }
+      }
+    }
+  };

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

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright (c) 2016 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import type { CSSResult } from 'lit';
+
+export const styles: CSSResult;

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

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright (c) 2016 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { css } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+
+export const styles = css`
+  :host {
+    align-items: flex-start;
+    justify-content: flex-start;
+  }
+
+  :host([right-aligned]),
+  :host([end-aligned]) {
+    align-items: flex-end;
+  }
+
+  :host([bottom-aligned]) {
+    justify-content: flex-end;
+  }
+
+  [part='overlay'] {
+    background-color: #fff;
+  }
+`;

package/theme/lumo/vaadin-context-menu-item-styles.js

@@ -0,0 +1,46 @@
+import '@vaadin/vaadin-lumo-styles/color.js';
+import '@vaadin/vaadin-lumo-styles/font-icons.js';
+import '@vaadin/vaadin-lumo-styles/sizing.js';
+import '@vaadin/vaadin-lumo-styles/spacing.js';
+import { item } from '@vaadin/item/theme/lumo/vaadin-item-styles.js';
+import { css, registerStyles } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+
+const contextMenuItem = css`
+  /* :hover needed to workaround https://github.com/vaadin/web-components/issues/3133 */
+  :host(:hover) {
+    user-select: none;
+    -ms-user-select: none;
+    -webkit-user-select: none;
+  }
+
+  :host([role='menuitem'][menu-item-checked]) [part='checkmark']::before {
+    opacity: 1;
+  }
+
+  :host([aria-haspopup='true'])::after {
+    font-family: lumo-icons;
+    font-size: var(--lumo-icon-size-xs);
+    content: var(--lumo-icons-angle-right);
+    color: var(--lumo-tertiary-text-color);
+  }
+
+  :host(:not([dir='rtl'])[aria-haspopup='true'])::after {
+    margin-right: calc(var(--lumo-space-m) * -1);
+    padding-left: var(--lumo-space-m);
+  }
+
+  :host([expanded]) {
+    background-color: var(--lumo-primary-color-10pct);
+  }
+
+  /* RTL styles */
+  :host([dir='rtl'][aria-haspopup='true'])::after {
+    content: var(--lumo-icons-angle-left);
+    margin-left: calc(var(--lumo-space-m) * -1);
+    padding-right: var(--lumo-space-m);
+  }
+`;
+
+registerStyles('vaadin-context-menu-item', [item, contextMenuItem], { moduleId: 'lumo-context-menu-item' });
+
+export { contextMenuItem };

package/theme/lumo/vaadin-context-menu-list-box-styles.js

@@ -0,0 +1,47 @@
+import '@vaadin/vaadin-lumo-styles/color.js';
+import '@vaadin/vaadin-lumo-styles/spacing.js';
+import '@vaadin/vaadin-lumo-styles/style.js';
+import { listBox } from '@vaadin/list-box/theme/lumo/vaadin-list-box-styles.js';
+import { css, registerStyles } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+
+const contextMenuListBox = css`
+  :host {
+    --_lumo-list-box-item-selected-icon-display: block;
+  }
+
+  /* Normal item */
+  [part='items'] ::slotted([role='menuitem']) {
+    -webkit-tap-highlight-color: var(--lumo-primary-color-10pct);
+    cursor: default;
+    outline: none;
+    border-radius: var(--lumo-border-radius-m);
+    padding-left: calc(var(--lumo-border-radius-m) / 4);
+    padding-right: calc(var(--lumo-space-l) + var(--lumo-border-radius-m) / 4);
+  }
+
+  /* Hovered item */
+  /* TODO a workaround until we have "focus-follows-mouse". After that, use the hover style for focus-ring as well */
+  [part='items'] ::slotted([role='menuitem']:hover:not([disabled])),
+  [part='items'] ::slotted([role='menuitem'][expanded]:not([disabled])) {
+    background-color: var(--lumo-primary-color-10pct);
+  }
+
+  /* RTL styles */
+  :host([dir='rtl']) [part='items'] ::slotted([role='menuitem']) {
+    padding-left: calc(var(--lumo-space-l) + var(--lumo-border-radius-m) / 4);
+    padding-right: calc(var(--lumo-border-radius-m) / 4);
+  }
+
+  /* Focused item */
+  @media (pointer: coarse) {
+    [part='items'] ::slotted([role='menuitem']:hover:not([expanded]):not([disabled])) {
+      background-color: transparent;
+    }
+  }
+`;
+
+registerStyles('vaadin-context-menu-list-box', [listBox, contextMenuListBox], {
+  moduleId: 'lumo-context-menu-list-box',
+});
+
+export { contextMenuListBox };

package/theme/lumo/vaadin-context-menu-overlay-styles.js

@@ -0,0 +1,33 @@
+import '@vaadin/vaadin-lumo-styles/spacing.js';
+import '@vaadin/vaadin-lumo-styles/style.js';
+import { menuOverlay } from '@vaadin/vaadin-lumo-styles/mixins/menu-overlay.js';
+import { css, registerStyles } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+
+const contextMenuOverlay = css`
+  :host([phone]) {
+    top: 0 !important;
+    right: 0 !important;
+    bottom: var(--vaadin-overlay-viewport-bottom) !important;
+    left: 0 !important;
+    align-items: stretch;
+    justify-content: flex-end;
+  }
+
+  /* TODO These style overrides should not be needed.
+   We should instead offer a way to have non-selectable items inside the context menu. */
+
+  :host {
+    --_lumo-list-box-item-selected-icon-display: none;
+    --_lumo-list-box-item-padding-left: calc(var(--lumo-space-m) + var(--lumo-border-radius-m) / 4);
+  }
+
+  [part='overlay'] {
+    outline: none;
+  }
+`;
+
+registerStyles('vaadin-context-menu-overlay', [menuOverlay, contextMenuOverlay], {
+  moduleId: 'lumo-context-menu-overlay',
+});
+
+export { contextMenuOverlay };

package/theme/lumo/vaadin-context-menu.js

@@ -1,5 +1,5 @@
-import './vaadin-context-menu-styles.js';
-import '@vaadin/item/theme/lumo/vaadin-item.js';
-import '@vaadin/list-box/theme/lumo/vaadin-list-box.js';
+import './vaadin-context-menu-item-styles.js';
+import './vaadin-context-menu-list-box-styles.js';
+import './vaadin-context-menu-overlay-styles.js';
 import '@vaadin/overlay/theme/lumo/vaadin-overlay.js';
 import '../../src/vaadin-context-menu.js';

package/theme/material/vaadin-context-menu-item-styles.js

@@ -0,0 +1,36 @@
+import '@vaadin/vaadin-material-styles/font-icons.js';
+import '@vaadin/vaadin-material-styles/color.js';
+import '@vaadin/vaadin-material-styles/typography.js';
+import { item } from '@vaadin/item/theme/material/vaadin-item-styles.js';
+import { css, registerStyles } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+
+const contextMenuItem = css`
+  :host([aria-haspopup='true'])::after {
+    font-family: material-icons;
+    font-size: var(--material-icon-font-size);
+  }
+
+  :host(:not([dir='rtl'])[aria-haspopup='true'])::after {
+    content: var(--material-icons-chevron-right);
+    padding-left: 9px;
+    margin-right: -9px;
+  }
+
+  :host([dir='rtl'][aria-haspopup='true'])::after {
+    content: var(--material-icons-chevron-left);
+    padding-right: 9px;
+    margin-left: -9px;
+  }
+
+  :host([menu-item-checked]) [part='checkmark']::before {
+    content: var(--material-icons-check);
+  }
+
+  :host([expanded]) {
+    background-color: var(--material-secondary-background-color);
+  }
+`;
+
+registerStyles('vaadin-context-menu-item', [item, contextMenuItem], { moduleId: 'material-context-menu-item' });
+
+export { contextMenuItem };

package/theme/material/vaadin-context-menu-list-box-styles.js

@@ -0,0 +1,38 @@
+import '@vaadin/vaadin-material-styles/color.js';
+import '@vaadin/vaadin-material-styles/typography.js';
+import { listBox } from '@vaadin/list-box/theme/material/vaadin-list-box-styles.js';
+import { css, registerStyles } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+
+const contextMenuListBox = css`
+  [part='items'] ::slotted([role='menuitem']) {
+    min-height: 36px;
+    padding: 8px 32px 8px 10px;
+    font-size: var(--material-small-font-size);
+    line-height: 24px;
+  }
+
+  :host([dir='rtl']) [part='items'] ::slotted([role='menuitem']) {
+    padding: 8px 10px 8px 32px;
+  }
+
+  [part='items'] ::slotted([role='menuitem']:hover:not([disabled])) {
+    background-color: var(--material-secondary-background-color);
+  }
+
+  [part='items'] ::slotted([role='menuitem'][focused]:not([disabled])) {
+    background-color: var(--material-divider-color);
+  }
+
+  @media (pointer: coarse) {
+    [part='items'] ::slotted([role='menuitem']:hover:not([disabled])),
+    [part='items'] ::slotted([role='menuitem'][focused]:not([disabled])) {
+      background-color: transparent;
+    }
+  }
+`;
+
+registerStyles('vaadin-context-menu-list-box', [listBox, contextMenuListBox], {
+  moduleId: 'material-context-menu-list-box',
+});
+
+export { contextMenuListBox };

package/theme/material/vaadin-context-menu-overlay-styles.js

@@ -0,0 +1,15 @@
+import { menuOverlay } from '@vaadin/vaadin-material-styles/mixins/menu-overlay.js';
+import { css, registerStyles } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+
+const contextMenuOverlay = css`
+  [part='overlay'] {
+    outline: none;
+    will-change: transform, opacity;
+  }
+`;
+
+registerStyles('vaadin-context-menu-overlay', [menuOverlay, contextMenuOverlay], {
+  moduleId: 'material-context-menu-overlay',
+});
+
+export { contextMenuOverlay };

package/theme/material/vaadin-context-menu.js

@@ -1,5 +1,5 @@
-import './vaadin-context-menu-styles.js';
-import '@vaadin/item/theme/material/vaadin-item.js';
-import '@vaadin/list-box/theme/material/vaadin-list-box.js';
+import './vaadin-context-menu-item-styles.js';
+import './vaadin-context-menu-list-box-styles.js';
+import './vaadin-context-menu-overlay-styles.js';
 import '@vaadin/overlay/theme/material/vaadin-overlay.js';
 import '../../src/vaadin-context-menu.js';

package/web-types.json

@@ -1,15 +1,26 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/context-menu",
-  "version": "24.0.0-alpha8",
+  "version": "24.0.0-alpha12",
   "description-markup": "markdown",
   "contributions": {
     "html": {
       "elements": [
         {
           "name": "vaadin-context-menu",
-          "description": "`<vaadin-context-menu>` is a Web Component for creating context menus.\n\n### Items\n\nItems is a higher level convenience API for defining a (hierarchical) menu structure for the component.\nIf a menu item has a non-empty `children` set, a sub-menu with the child items is opened\nnext to the parent menu on mouseover, tap or a right arrow keypress.\n\nWhen an item is selected, `<vaadin-context-menu>` dispatches an \"item-selected\" event\nwith the selected item as `event.detail.value` property.\n\n```javascript\ncontextMenu.items = [\n  {text: 'Menu Item 1', theme: 'primary', children:\n    [\n      {text: 'Menu Item 1-1', checked: true},\n      {text: 'Menu Item 1-2'}\n    ]\n  },\n  {component: 'hr'},\n  {text: 'Menu Item 2', children:\n    [\n      {text: 'Menu Item 2-1'},\n      {text: 'Menu Item 2-2', disabled: true}\n    ]\n  },\n  {text: 'Menu Item 3', disabled: true}\n];\n\ncontextMenu.addEventListener('item-selected', e => {\n  const item = e.detail.value;\n  console.log(`${item.text} selected`);\n});\n```\n\n**NOTE:** when the `items` array is defined, the renderer cannot be used.\n\n### Rendering\n\nThe content of the menu can be populated by using the renderer callback function.\n\nThe renderer function provides `root`, `contextMenu`, `model` arguments when applicable.\nGenerate DOM content by using `model` object properties if needed, append it to the `root`\nelement and control the state of the host element by accessing `contextMenu`. Before generating\nnew content, the renderer function should check if there is already content in `root` for reusing it.\n\n```html\n<vaadin-context-menu id=\"contextMenu\">\n <p>This paragraph has a context menu.</p>\n</vaadin-context-menu>\n```\n```js\nconst contextMenu = document.querySelector('#contextMenu');\ncontextMenu.renderer = (root, contextMenu, context) => {\n  let listBox = root.firstElementChild;\n  if (!listBox) {\n    listBox = document.createElement('vaadin-list-box');\n    root.appendChild(listBox);\n  }\n\n  let item = listBox.querySelector('vaadin-item');\n  if (!item) {\n    item = document.createElement('vaadin-item');\n    listBox.appendChild(item);\n  }\n  item.textContent = 'Content of the selector: ' + context.target.textContent;\n};\n```\n\nYou can access the menu context inside the renderer using\n`context.target` and `context.detail`.\n\nRenderer is called on the opening of the context-menu and each time the related context is updated.\nDOM generated during the renderer call can be reused\nin the next renderer call and will be provided with the `root` argument.\nOn first call it will be empty.\n\n### “vaadin-contextmenu” Gesture Event\n\n`vaadin-contextmenu` is a gesture event (a custom event),\nwhich is dispatched after either `contextmenu` or long touch events.\nThis enables support for both mouse and touch environments in a uniform way.\n\n`<vaadin-context-menu>` opens the menu overlay on the `vaadin-contextmenu`\nevent by default.\n\n### Menu Listener\n\nBy default, the `<vaadin-context-menu>` element listens for the menu opening\nevent on itself. In case if you do not want to wrap the target, you can listen for\nevents on an element outside the `<vaadin-context-menu>` by setting the\n`listenOn` property:\n\n```html\n<vaadin-context-menu id=\"contextMenu\"></vaadin-context-menu>\n\n<div id=\"menuListener\">The element that listens for the contextmenu event.</div>\n```\n```javascript\nconst contextMenu = document.querySelector('#contextMenu');\ncontextMenu.listenOn = document.querySelector('#menuListener');\n```\n\n### Filtering Menu Targets\n\nBy default, the listener element and all its descendants open the context\nmenu. You can filter the menu targets to a smaller set of elements inside\nthe listener element by setting the `selector` property.\n\nIn the following example, only the elements matching `.has-menu` will open the context menu:\n\n```html\n<vaadin-context-menu selector=\".has-menu\">\n  <p class=\"has-menu\">This paragraph opens the context menu</p>\n  <p>This paragraph does not open the context menu</p>\n</vaadin-context-menu>\n```\n\n### Menu Context\n\nThe following properties are available in the `context` argument:\n\n- `target` is the menu opening event target, which is the element that\nthe user has called the context menu for\n- `detail` is the menu opening event detail\n\nIn the following example, the menu item text is composed with the contents\nof the element that opened the menu:\n\n```html\n<vaadin-context-menu selector=\"li\" id=\"contextMenu\">\n  <ul>\n    <li>Foo</li>\n    <li>Bar</li>\n    <li>Baz</li>\n  </ul>\n</vaadin-context-menu>\n```\n```js\nconst contextMenu = document.querySelector('#contextMenu');\ncontextMenu.renderer = (root, contextMenu, context) => {\n  let listBox = root.firstElementChild;\n  if (!listBox) {\n    listBox = document.createElement('vaadin-list-box');\n    root.appendChild(listBox);\n  }\n\n  let item = listBox.querySelector('vaadin-item');\n  if (!item) {\n    item = document.createElement('vaadin-item');\n    listBox.appendChild(item);\n  }\n  item.textContent = 'The menu target: ' + context.target.textContent;\n};\n```\n\n### Styling\n\n`<vaadin-context-menu>` uses `<vaadin-context-menu-overlay>` internal\nthemable component as the actual visible context menu overlay.\n\nSee [`<vaadin-overlay>`](https://cdn.vaadin.com/vaadin-web-components/24.0.0-alpha8/#/elements/vaadin-overlay)\ndocumentation for `<vaadin-context-menu-overlay>` stylable parts.\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/custom-theme/styling-components) documentation.\n\n### Internal components\n\nWhen using `items` API, in addition `<vaadin-context-menu-overlay>`, the following\ninternal components are themable:\n\n- `<vaadin-context-menu-item>` - has the same API as [`<vaadin-item>`](https://cdn.vaadin.com/vaadin-web-components/24.0.0-alpha8/#/elements/vaadin-item).\n- `<vaadin-context-menu-list-box>` - has the same API as [`<vaadin-list-box>`](https://cdn.vaadin.com/vaadin-web-components/24.0.0-alpha8/#/elements/vaadin-list-box).\n\nNote: the `theme` attribute value set on `<vaadin-context-menu>` is\npropagated to the internal components listed above.",
+          "description": "`<vaadin-context-menu>` is a Web Component for creating context menus.\n\n### Items\n\nItems is a higher level convenience API for defining a (hierarchical) menu structure for the component.\nIf a menu item has a non-empty `children` set, a sub-menu with the child items is opened\nnext to the parent menu on mouseover, tap or a right arrow keypress.\n\nWhen an item is selected, `<vaadin-context-menu>` dispatches an \"item-selected\" event\nwith the selected item as `event.detail.value` property.\n\n```javascript\ncontextMenu.items = [\n  {text: 'Menu Item 1', theme: 'primary', children:\n    [\n      {text: 'Menu Item 1-1', checked: true},\n      {text: 'Menu Item 1-2'}\n    ]\n  },\n  {component: 'hr'},\n  {text: 'Menu Item 2', children:\n    [\n      {text: 'Menu Item 2-1'},\n      {text: 'Menu Item 2-2', disabled: true}\n    ]\n  },\n  {text: 'Menu Item 3', disabled: true}\n];\n\ncontextMenu.addEventListener('item-selected', e => {\n  const item = e.detail.value;\n  console.log(`${item.text} selected`);\n});\n```\n\n**NOTE:** when the `items` array is defined, the renderer cannot be used.\n\n### Rendering\n\nThe content of the menu can be populated by using the renderer callback function.\n\nThe renderer function provides `root`, `contextMenu`, `model` arguments when applicable.\nGenerate DOM content by using `model` object properties if needed, append it to the `root`\nelement and control the state of the host element by accessing `contextMenu`. Before generating\nnew content, the renderer function should check if there is already content in `root` for reusing it.\n\n```html\n<vaadin-context-menu id=\"contextMenu\">\n <p>This paragraph has a context menu.</p>\n</vaadin-context-menu>\n```\n```js\nconst contextMenu = document.querySelector('#contextMenu');\ncontextMenu.renderer = (root, contextMenu, context) => {\n  let listBox = root.firstElementChild;\n  if (!listBox) {\n    listBox = document.createElement('vaadin-list-box');\n    root.appendChild(listBox);\n  }\n\n  let item = listBox.querySelector('vaadin-item');\n  if (!item) {\n    item = document.createElement('vaadin-item');\n    listBox.appendChild(item);\n  }\n  item.textContent = 'Content of the selector: ' + context.target.textContent;\n};\n```\n\nYou can access the menu context inside the renderer using\n`context.target` and `context.detail`.\n\nRenderer is called on the opening of the context-menu and each time the related context is updated.\nDOM generated during the renderer call can be reused\nin the next renderer call and will be provided with the `root` argument.\nOn first call it will be empty.\n\n### “vaadin-contextmenu” Gesture Event\n\n`vaadin-contextmenu` is a gesture event (a custom event),\nwhich is dispatched after either `contextmenu` or long touch events.\nThis enables support for both mouse and touch environments in a uniform way.\n\n`<vaadin-context-menu>` opens the menu overlay on the `vaadin-contextmenu`\nevent by default.\n\n### Menu Listener\n\nBy default, the `<vaadin-context-menu>` element listens for the menu opening\nevent on itself. In case if you do not want to wrap the target, you can listen for\nevents on an element outside the `<vaadin-context-menu>` by setting the\n`listenOn` property:\n\n```html\n<vaadin-context-menu id=\"contextMenu\"></vaadin-context-menu>\n\n<div id=\"menuListener\">The element that listens for the contextmenu event.</div>\n```\n```javascript\nconst contextMenu = document.querySelector('#contextMenu');\ncontextMenu.listenOn = document.querySelector('#menuListener');\n```\n\n### Filtering Menu Targets\n\nBy default, the listener element and all its descendants open the context\nmenu. You can filter the menu targets to a smaller set of elements inside\nthe listener element by setting the `selector` property.\n\nIn the following example, only the elements matching `.has-menu` will open the context menu:\n\n```html\n<vaadin-context-menu selector=\".has-menu\">\n  <p class=\"has-menu\">This paragraph opens the context menu</p>\n  <p>This paragraph does not open the context menu</p>\n</vaadin-context-menu>\n```\n\n### Menu Context\n\nThe following properties are available in the `context` argument:\n\n- `target` is the menu opening event target, which is the element that\nthe user has called the context menu for\n- `detail` is the menu opening event detail\n\nIn the following example, the menu item text is composed with the contents\nof the element that opened the menu:\n\n```html\n<vaadin-context-menu selector=\"li\" id=\"contextMenu\">\n  <ul>\n    <li>Foo</li>\n    <li>Bar</li>\n    <li>Baz</li>\n  </ul>\n</vaadin-context-menu>\n```\n```js\nconst contextMenu = document.querySelector('#contextMenu');\ncontextMenu.renderer = (root, contextMenu, context) => {\n  let listBox = root.firstElementChild;\n  if (!listBox) {\n    listBox = document.createElement('vaadin-list-box');\n    root.appendChild(listBox);\n  }\n\n  let item = listBox.querySelector('vaadin-item');\n  if (!item) {\n    item = document.createElement('vaadin-item');\n    listBox.appendChild(item);\n  }\n  item.textContent = 'The menu target: ' + context.target.textContent;\n};\n```\n\n### Styling\n\n`<vaadin-context-menu>` uses `<vaadin-context-menu-overlay>` internal\nthemable component as the actual visible context menu overlay.\n\nSee [`<vaadin-overlay>`](https://cdn.vaadin.com/vaadin-web-components/24.0.0-alpha12/#/elements/vaadin-overlay)\ndocumentation for `<vaadin-context-menu-overlay>` stylable parts.\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/custom-theme/styling-components) documentation.\n\n### Internal components\n\nWhen using `items` API, in addition `<vaadin-context-menu-overlay>`, the following\ninternal components are themable:\n\n- `<vaadin-context-menu-item>` - has the same API as [`<vaadin-item>`](https://cdn.vaadin.com/vaadin-web-components/24.0.0-alpha12/#/elements/vaadin-item).\n- `<vaadin-context-menu-list-box>` - has the same API as [`<vaadin-list-box>`](https://cdn.vaadin.com/vaadin-web-components/24.0.0-alpha12/#/elements/vaadin-list-box).\n\nNote: the `theme` attribute value set on `<vaadin-context-menu>` is\npropagated to the internal components listed above.",
           "attributes": [
+            {
+              "name": "overlay-class",
+              "description": "A space-delimited list of CSS class names to set on the overlay element.\nThis property does not affect other CSS class names set manually via JS.\n\nNote, if the CSS class name was set with this property, clearing it will\nremove it from the overlay, even if the same class name was also added\nmanually, e.g. by using `classList.add()` in the `renderer` function.",
+              "value": {
+                "type": [
+                  "string",
+                  "null",
+                  "undefined"
+                ]
+              }
+            },
             {
               "name": "selector",
               "description": "CSS selector that can be used to target any child element\nof the context menu to listen for `openOn` events.",
@@ -53,6 +64,17 @@
           ],
           "js": {
             "properties": [
+              {
+                "name": "overlayClass",
+                "description": "A space-delimited list of CSS class names to set on the overlay element.\nThis property does not affect other CSS class names set manually via JS.\n\nNote, if the CSS class name was set with this property, clearing it will\nremove it from the overlay, even if the same class name was also added\nmanually, e.g. by using `classList.add()` in the `renderer` function.",
+                "value": {
+                  "type": [
+                    "string",
+                    "null",
+                    "undefined"
+                  ]
+                }
+              },
               {
                 "name": "items",
                 "description": "Defines a (hierarchical) menu structure for the component.\nIf a menu item has a non-empty `children` set, a sub-menu with the child items is opened\nnext to the parent menu on mouseover, tap or a right arrow keypress.\n\nThe items API can't be used together with a renderer!\n\n#### Example\n\n```javascript\ncontextMenu.items = [\n  {text: 'Menu Item 1', theme: 'primary', children:\n    [\n      {text: 'Menu Item 1-1', checked: true},\n      {text: 'Menu Item 1-2'}\n    ]\n  },\n  {component: 'hr'},\n  {text: 'Menu Item 2', children:\n    [\n      {text: 'Menu Item 2-1'},\n      {text: 'Menu Item 2-2', disabled: true}\n    ]\n  },\n  {text: 'Menu Item 3', disabled: true}\n];\n```",