@vaadin/context-menu 25.3.0-alpha9 → 25.3.0-beta1

package/custom-elements.json

@@ -468,6 +468,16 @@
                 "name": "ItemsMixin",
                 "module": "src/vaadin-contextmenu-items-mixin.js"
               }
+            },
+            {
+              "name": "items-outside-click",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "inheritedFrom": {
+                "name": "ItemsMixin",
+                "module": "src/vaadin-contextmenu-items-mixin.js"
+              }
             }
           ],
           "attributes": [
@@ -788,7 +798,7 @@
               "type": {
                 "text": "CustomEvent"
               },
-              "description": "Fired when all menus should close, e.g., after pressing Tab or on submenu close.",
+              "description": "Fired when all menus should close, e.g., after pressing Tab or on submenu close. This event is deprecated and will be removed in Vaadin 26. Use `closed` instead.",
               "inheritedFrom": {
                 "name": "ItemsMixin",
                 "module": "src/vaadin-contextmenu-items-mixin.js"
@@ -817,11 +827,15 @@
               }
             },
             {
+              "name": "items-outside-click",
               "type": {
                 "text": "CustomEvent"
               },
-              "description": "Fired when a click happens outside any open sub-menus.",
-              "name": "items-outside-click"
+              "description": "Fired when a click happens outside any open sub-menus. This event is deprecated and will be removed in Vaadin 26. Use `closed` instead.",
+              "inheritedFrom": {
+                "name": "ItemsMixin",
+                "module": "src/vaadin-contextmenu-items-mixin.js"
+              }
             },
             {
               "type": {
@@ -995,6 +1009,12 @@
               "type": {
                 "text": "CustomEvent"
               }
+            },
+            {
+              "name": "items-outside-click",
+              "type": {
+                "text": "CustomEvent"
+              }
             }
           ],
           "attributes": [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/context-menu",
-  "version": "25.3.0-alpha9",
+  "version": "25.3.0-beta1",
   "publishConfig": {
     "access": "public"
   },
@@ -37,21 +37,21 @@
   ],
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
-    "@vaadin/a11y-base": "25.3.0-alpha9",
-    "@vaadin/component-base": "25.3.0-alpha9",
-    "@vaadin/item": "25.3.0-alpha9",
-    "@vaadin/list-box": "25.3.0-alpha9",
-    "@vaadin/lit-renderer": "25.3.0-alpha9",
-    "@vaadin/overlay": "25.3.0-alpha9",
-    "@vaadin/vaadin-themable-mixin": "25.3.0-alpha9",
+    "@vaadin/a11y-base": "25.3.0-beta1",
+    "@vaadin/component-base": "25.3.0-beta1",
+    "@vaadin/item": "25.3.0-beta1",
+    "@vaadin/list-box": "25.3.0-beta1",
+    "@vaadin/lit-renderer": "25.3.0-beta1",
+    "@vaadin/overlay": "25.3.0-beta1",
+    "@vaadin/vaadin-themable-mixin": "25.3.0-beta1",
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@vaadin/aura": "25.3.0-alpha9",
-    "@vaadin/chai-plugins": "25.3.0-alpha9",
-    "@vaadin/test-runner-commands": "25.3.0-alpha9",
+    "@vaadin/aura": "25.3.0-beta1",
+    "@vaadin/chai-plugins": "25.3.0-beta1",
+    "@vaadin/test-runner-commands": "25.3.0-beta1",
     "@vaadin/testing-helpers": "^2.0.0",
-    "@vaadin/vaadin-lumo-styles": "25.3.0-alpha9",
+    "@vaadin/vaadin-lumo-styles": "25.3.0-beta1",
     "sinon": "^22.0.0"
   },
   "customElements": "custom-elements.json",
@@ -59,5 +59,5 @@
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "cb915ebde095ec5b94a87af93dd4530f51984c52"
+  "gitHead": "295432e44a6967e1aff36462b2e3e1d0e64eb8cc"
 }

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

@@ -206,7 +206,8 @@ export const ContextMenuMixin = (superClass) =>
           );
         }
 
-        // With items property, menu closes on item selection or items-outside-click.
+        // Clicks on items bubble to the overlay and must not close the menu
+        // (items with `keepOpen` or with children), so disable `closeOn`.
         if (this.items && this.closeOn === 'click') {
           this.closeOn = '';
         }
@@ -224,9 +225,12 @@ export const ContextMenuMixin = (superClass) =>
       }
 
       const opened = event.detail.value;
-      this._setOpened(opened);
       if (opened) {
+        this._setOpened(true);
         this.__alignOverlayPosition();
+      } else if (this.opened) {
+        // Use `close()` to also reset menu-bar button on outside click.
+        this.close();
       }
     }
 
@@ -315,7 +319,11 @@ export const ContextMenuMixin = (superClass) =>
 
     /** @private */
     _preventDefault(e) {
-      e.preventDefault();
+      // With items, `closeOn` is cleared to not close the menu on clicks bubbling
+      // from the items to the overlay, and the menu still closes on outside click.
+      if (!this.items) {
+        e.preventDefault();
+      }
     }
 
     /** @private */

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

@@ -57,8 +57,14 @@ export interface ContextMenuCustomEventMap<TItem extends ContextMenuItemData = C
 
   'item-selected': ContextMenuItemSelectedEvent<TItem>;
 
+  /**
+   * @deprecated This event is deprecated and will be removed in Vaadin 26. Use `closed` instead.
+   */
   'close-all-menus': Event;
 
+  /**
+   * @deprecated This event is deprecated and will be removed in Vaadin 26. Use `closed` instead.
+   */
   'items-outside-click': Event;
 
   closed: ContextMenuClosedEvent;
@@ -303,8 +309,8 @@ export interface ContextMenuEventMap<TItem extends ContextMenuItemData = Context
  * @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.
- * @fires {CustomEvent} close-all-menus - Fired when all menus should close, e.g., after pressing Tab or on submenu close.
- * @fires {CustomEvent} items-outside-click - Fired when a click happens outside any open sub-menus.
+ * @fires {CustomEvent} close-all-menus - Fired when all menus should close, e.g., after pressing Tab or on submenu close. This event is deprecated and will be removed in Vaadin 26. Use `closed` instead.
+ * @fires {CustomEvent} items-outside-click - Fired when a click happens outside any open sub-menus. This event is deprecated and will be removed in Vaadin 26. Use `closed` instead.
  */
 declare class ContextMenu<TItem extends ContextMenuItemData = ContextMenuItemData> extends HTMLElement {
   /**

package/src/vaadin-context-menu.js

@@ -251,8 +251,8 @@ import { ContextMenuMixin } from './vaadin-context-menu-mixin.js';
  * @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.
- * @fires {CustomEvent} close-all-menus - Fired when all menus should close, e.g., after pressing Tab or on submenu close.
- * @fires {CustomEvent} items-outside-click - Fired when a click happens outside any open sub-menus.
+ * @fires {CustomEvent} close-all-menus - Fired when all menus should close, e.g., after pressing Tab or on submenu close. This event is deprecated and will be removed in Vaadin 26. Use `closed` instead.
+ * @fires {CustomEvent} items-outside-click - Fired when a click happens outside any open sub-menus. This event is deprecated and will be removed in Vaadin 26. Use `closed` instead.
  *
  * @attr {string} theme - The theme variants to apply to the component.
  * @customElement vaadin-context-menu

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

@@ -87,21 +87,6 @@ export const ItemsMixin = (superClass) =>
       };
     }
 
-    constructor() {
-      super();
-
-      // Overlay's outside click listener doesn't work with modeless
-      // overlays (submenus) so we need additional logic for it
-      this.__itemsOutsideClickListener = (e) => {
-        if (this._shouldCloseOnOutsideClick(e)) {
-          this.dispatchEvent(new CustomEvent('items-outside-click'));
-        }
-      };
-      this.addEventListener('items-outside-click', () => {
-        this.items && this.close();
-      });
-    }
-
     /**
      * Tag name prefix used by overlay, list-box and items.
      * @protected
@@ -111,33 +96,12 @@ export const ItemsMixin = (superClass) =>
       return 'vaadin-context-menu';
     }
 
-    /** @protected */
-    connectedCallback() {
-      super.connectedCallback();
-      // Firefox leaks click to document on contextmenu even if prevented
-      // https://bugzilla.mozilla.org/show_bug.cgi?id=990614
-      document.documentElement.addEventListener('click', this.__itemsOutsideClickListener);
-    }
-
     /** @protected */
     disconnectedCallback() {
       super.disconnectedCallback();
-      document.documentElement.removeEventListener('click', this.__itemsOutsideClickListener);
       this._tooltipController.setTarget(null);
     }
 
-    /**
-     * Whether to close the overlay on outside click or not.
-     * Override this method to customize the closing logic.
-     *
-     * @param {Event} event
-     * @return {boolean}
-     * @protected
-     */
-    _shouldCloseOnOutsideClick(event) {
-      return !event.composedPath().some((el) => el.localName === `${this._tagNamePrefix}-overlay`);
-    }
-
     /** @protected */
     __forwardFocus() {
       const overlay = this._overlayElement;
@@ -290,6 +254,11 @@ export const ItemsMixin = (superClass) =>
         this.close();
       });
 
+      // TODO: deprecated, fires for backwards compatibility. Remove in Vaadin 26
+      overlay.addEventListener('vaadin-overlay-outside-click', () => {
+        this.dispatchEvent(new CustomEvent('items-outside-click'));
+      });
+
       // 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) => {

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

@@ -85,6 +85,34 @@ export const MenuOverlayMixin = (superClass) =>
       this.close();
     }
 
+    /**
+     * Override method from `OverlayMixin` to close the menu from its root overlay.
+     *
+     * @param {Event} event
+     * @return {boolean}
+     * @protected
+     * @override
+     */
+    _shouldCloseOnOutsideClick(event) {
+      // Only close the menu from its root overlay
+      if (this.parentOverlay) {
+        return false;
+      }
+
+      // Ignore clicks on nested menu items
+      if (event.composedPath().includes(this)) {
+        return false;
+      }
+
+      // With items, overlays above the root overlay belong to the menu itself,
+      // e.g. an open sub-menu or item tooltip, so ignore the overlay stack
+      if (this.owner.items) {
+        return true;
+      }
+
+      return super._shouldCloseOnOutsideClick(event);
+    }
+
     /**
      * Returns the adjusted boundaries of the overlay.
      *

package/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/context-menu",
-  "version": "25.3.0-alpha9",
+  "version": "25.3.0-beta1",
   "description-markup": "markdown",
   "contributions": {
     "html": {
@@ -129,7 +129,7 @@
         },
         {
           "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.\nIf item does not have `keepOpen` property the menu will be closed.\n\n```javascript\ncontextMenu.items = [\n  { text: 'Menu Item 1', theme: 'primary', className: 'first', children:\n    [\n      { text: 'Menu Item 1-1', checked: true, keepOpen: 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, className: 'last' }\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#### Disabled menu items\n\nWhen disabled, menu items are rendered as \"dimmed\".\n\nBy default, disabled items are not focusable and don't react to hover.\nAs a result, they are hidden from assistive technologies, and it's not\npossible to show a tooltip to explain why they are disabled. This can\nbe addressed by enabling the feature flag `accessibleDisabledMenuItems`,\nwhich makes disabled items focusable and hoverable, while still\npreventing them from being activated:\n\n```js\n// Set before any context menu is attached to the DOM.\nwindow.Vaadin.featureFlags.accessibleDisabledMenuItems = true;\n```\n\n#### Item tooltips\n\nMenu items can have tooltips that are shown on hover and keyboard\nfocus. To enable them, add a slotted `<vaadin-tooltip>` element\nand set the `tooltip` property on each item that should have one:\n\n```html\n<vaadin-context-menu>\n  <vaadin-tooltip slot=\"tooltip\"></vaadin-tooltip>\n</vaadin-context-menu>\n```\n\n### Slotted list-box\n\nThe content of the menu can also be populated by providing a custom\n`<vaadin-context-menu-list-box>` with the `overlay` slot:\n\n```html\n<vaadin-context-menu>\n  <vaadin-context-menu-list-box slot=\"overlay\">\n    <vaadin-context-menu-item>Edit</vaadin-context-menu-item>\n    <vaadin-context-menu-item>Delete</vaadin-context-menu-item>\n  </vaadin-context-menu-list-box>\n</vaadin-context-menu>\n```\n\n**Note:** slotted list-box supports a single root-level menu only and\ncannot be combined with the `items` or `renderer` API.\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\nThe following shadow DOM parts are available for styling:\n\nPart name        | Description\n-----------------|-------------------------------------------\n`backdrop`       | Backdrop of the overlay\n`overlay`        | The overlay container\n`content`        | The overlay content\n\n### Custom CSS Properties\n\nThe following custom CSS properties are available for styling:\n\nCustom CSS property                   | Description\n--------------------------------------|-------------\n`--vaadin-context-menu-offset-top`    | Used as an offset when using `position` and the context menu is aligned vertically below the target\n`--vaadin-context-menu-offset-bottom` | Used as an offset when using `position` and the context menu is aligned vertically above the target\n`--vaadin-context-menu-offset-start`  | Used as an offset when using `position` and the context menu is aligned horizontally after the target\n`--vaadin-context-menu-offset-end`    | Used as an offset when using `position` and the context menu is aligned horizontally before the target\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.\n\n### Related components\n\nIn addition to `<vaadin-context-menu>` itself, the following components are themable:\n\n- [`<vaadin-context-menu-item>`](https://cdn.vaadin.com/vaadin-web-components/25.3.0-alpha9/#/elements/vaadin-context-menu-item) - an item element.\n- [`<vaadin-context-menu-list-box>`](https://cdn.vaadin.com/vaadin-web-components/25.3.0-alpha9/#/elements/vaadin-context-menu-list-box) - a list-box element.",
+          "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.\nIf item does not have `keepOpen` property the menu will be closed.\n\n```javascript\ncontextMenu.items = [\n  { text: 'Menu Item 1', theme: 'primary', className: 'first', children:\n    [\n      { text: 'Menu Item 1-1', checked: true, keepOpen: 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, className: 'last' }\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#### Disabled menu items\n\nWhen disabled, menu items are rendered as \"dimmed\".\n\nBy default, disabled items are not focusable and don't react to hover.\nAs a result, they are hidden from assistive technologies, and it's not\npossible to show a tooltip to explain why they are disabled. This can\nbe addressed by enabling the feature flag `accessibleDisabledMenuItems`,\nwhich makes disabled items focusable and hoverable, while still\npreventing them from being activated:\n\n```js\n// Set before any context menu is attached to the DOM.\nwindow.Vaadin.featureFlags.accessibleDisabledMenuItems = true;\n```\n\n#### Item tooltips\n\nMenu items can have tooltips that are shown on hover and keyboard\nfocus. To enable them, add a slotted `<vaadin-tooltip>` element\nand set the `tooltip` property on each item that should have one:\n\n```html\n<vaadin-context-menu>\n  <vaadin-tooltip slot=\"tooltip\"></vaadin-tooltip>\n</vaadin-context-menu>\n```\n\n### Slotted list-box\n\nThe content of the menu can also be populated by providing a custom\n`<vaadin-context-menu-list-box>` with the `overlay` slot:\n\n```html\n<vaadin-context-menu>\n  <vaadin-context-menu-list-box slot=\"overlay\">\n    <vaadin-context-menu-item>Edit</vaadin-context-menu-item>\n    <vaadin-context-menu-item>Delete</vaadin-context-menu-item>\n  </vaadin-context-menu-list-box>\n</vaadin-context-menu>\n```\n\n**Note:** slotted list-box supports a single root-level menu only and\ncannot be combined with the `items` or `renderer` API.\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\nThe following shadow DOM parts are available for styling:\n\nPart name        | Description\n-----------------|-------------------------------------------\n`backdrop`       | Backdrop of the overlay\n`overlay`        | The overlay container\n`content`        | The overlay content\n\n### Custom CSS Properties\n\nThe following custom CSS properties are available for styling:\n\nCustom CSS property                   | Description\n--------------------------------------|-------------\n`--vaadin-context-menu-offset-top`    | Used as an offset when using `position` and the context menu is aligned vertically below the target\n`--vaadin-context-menu-offset-bottom` | Used as an offset when using `position` and the context menu is aligned vertically above the target\n`--vaadin-context-menu-offset-start`  | Used as an offset when using `position` and the context menu is aligned horizontally after the target\n`--vaadin-context-menu-offset-end`    | Used as an offset when using `position` and the context menu is aligned horizontally before the target\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.\n\n### Related components\n\nIn addition to `<vaadin-context-menu>` itself, the following components are themable:\n\n- [`<vaadin-context-menu-item>`](https://cdn.vaadin.com/vaadin-web-components/25.3.0-beta1/#/elements/vaadin-context-menu-item) - an item element.\n- [`<vaadin-context-menu-list-box>`](https://cdn.vaadin.com/vaadin-web-components/25.3.0-beta1/#/elements/vaadin-context-menu-list-box) - a list-box element.",
           "attributes": [
             {
               "name": "close-on",
@@ -248,7 +248,7 @@
             "events": [
               {
                 "name": "close-all-menus",
-                "description": "Fired when all menus should close, e.g., after pressing Tab or on submenu close."
+                "description": "Fired when all menus should close, e.g., after pressing Tab or on submenu close. This event is deprecated and will be removed in Vaadin 26. Use `closed` instead."
               },
               {
                 "name": "closed",
@@ -260,7 +260,7 @@
               },
               {
                 "name": "items-outside-click",
-                "description": "Fired when a click happens outside any open sub-menus."
+                "description": "Fired when a click happens outside any open sub-menus. This event is deprecated and will be removed in Vaadin 26. Use `closed` instead."
               },
               {
                 "name": "opened-changed",

package/web-types.lit.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/context-menu",
-  "version": "25.3.0-alpha9",
+  "version": "25.3.0-beta1",
   "description-markup": "markdown",
   "framework": "lit",
   "framework-config": {
@@ -65,7 +65,7 @@
         },
         {
           "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.\nIf item does not have `keepOpen` property the menu will be closed.\n\n```javascript\ncontextMenu.items = [\n  { text: 'Menu Item 1', theme: 'primary', className: 'first', children:\n    [\n      { text: 'Menu Item 1-1', checked: true, keepOpen: 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, className: 'last' }\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#### Disabled menu items\n\nWhen disabled, menu items are rendered as \"dimmed\".\n\nBy default, disabled items are not focusable and don't react to hover.\nAs a result, they are hidden from assistive technologies, and it's not\npossible to show a tooltip to explain why they are disabled. This can\nbe addressed by enabling the feature flag `accessibleDisabledMenuItems`,\nwhich makes disabled items focusable and hoverable, while still\npreventing them from being activated:\n\n```js\n// Set before any context menu is attached to the DOM.\nwindow.Vaadin.featureFlags.accessibleDisabledMenuItems = true;\n```\n\n#### Item tooltips\n\nMenu items can have tooltips that are shown on hover and keyboard\nfocus. To enable them, add a slotted `<vaadin-tooltip>` element\nand set the `tooltip` property on each item that should have one:\n\n```html\n<vaadin-context-menu>\n  <vaadin-tooltip slot=\"tooltip\"></vaadin-tooltip>\n</vaadin-context-menu>\n```\n\n### Slotted list-box\n\nThe content of the menu can also be populated by providing a custom\n`<vaadin-context-menu-list-box>` with the `overlay` slot:\n\n```html\n<vaadin-context-menu>\n  <vaadin-context-menu-list-box slot=\"overlay\">\n    <vaadin-context-menu-item>Edit</vaadin-context-menu-item>\n    <vaadin-context-menu-item>Delete</vaadin-context-menu-item>\n  </vaadin-context-menu-list-box>\n</vaadin-context-menu>\n```\n\n**Note:** slotted list-box supports a single root-level menu only and\ncannot be combined with the `items` or `renderer` API.\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\nThe following shadow DOM parts are available for styling:\n\nPart name        | Description\n-----------------|-------------------------------------------\n`backdrop`       | Backdrop of the overlay\n`overlay`        | The overlay container\n`content`        | The overlay content\n\n### Custom CSS Properties\n\nThe following custom CSS properties are available for styling:\n\nCustom CSS property                   | Description\n--------------------------------------|-------------\n`--vaadin-context-menu-offset-top`    | Used as an offset when using `position` and the context menu is aligned vertically below the target\n`--vaadin-context-menu-offset-bottom` | Used as an offset when using `position` and the context menu is aligned vertically above the target\n`--vaadin-context-menu-offset-start`  | Used as an offset when using `position` and the context menu is aligned horizontally after the target\n`--vaadin-context-menu-offset-end`    | Used as an offset when using `position` and the context menu is aligned horizontally before the target\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.\n\n### Related components\n\nIn addition to `<vaadin-context-menu>` itself, the following components are themable:\n\n- [`<vaadin-context-menu-item>`](https://cdn.vaadin.com/vaadin-web-components/25.3.0-alpha9/#/elements/vaadin-context-menu-item) - an item element.\n- [`<vaadin-context-menu-list-box>`](https://cdn.vaadin.com/vaadin-web-components/25.3.0-alpha9/#/elements/vaadin-context-menu-list-box) - a list-box element.",
+          "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.\nIf item does not have `keepOpen` property the menu will be closed.\n\n```javascript\ncontextMenu.items = [\n  { text: 'Menu Item 1', theme: 'primary', className: 'first', children:\n    [\n      { text: 'Menu Item 1-1', checked: true, keepOpen: 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, className: 'last' }\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#### Disabled menu items\n\nWhen disabled, menu items are rendered as \"dimmed\".\n\nBy default, disabled items are not focusable and don't react to hover.\nAs a result, they are hidden from assistive technologies, and it's not\npossible to show a tooltip to explain why they are disabled. This can\nbe addressed by enabling the feature flag `accessibleDisabledMenuItems`,\nwhich makes disabled items focusable and hoverable, while still\npreventing them from being activated:\n\n```js\n// Set before any context menu is attached to the DOM.\nwindow.Vaadin.featureFlags.accessibleDisabledMenuItems = true;\n```\n\n#### Item tooltips\n\nMenu items can have tooltips that are shown on hover and keyboard\nfocus. To enable them, add a slotted `<vaadin-tooltip>` element\nand set the `tooltip` property on each item that should have one:\n\n```html\n<vaadin-context-menu>\n  <vaadin-tooltip slot=\"tooltip\"></vaadin-tooltip>\n</vaadin-context-menu>\n```\n\n### Slotted list-box\n\nThe content of the menu can also be populated by providing a custom\n`<vaadin-context-menu-list-box>` with the `overlay` slot:\n\n```html\n<vaadin-context-menu>\n  <vaadin-context-menu-list-box slot=\"overlay\">\n    <vaadin-context-menu-item>Edit</vaadin-context-menu-item>\n    <vaadin-context-menu-item>Delete</vaadin-context-menu-item>\n  </vaadin-context-menu-list-box>\n</vaadin-context-menu>\n```\n\n**Note:** slotted list-box supports a single root-level menu only and\ncannot be combined with the `items` or `renderer` API.\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\nThe following shadow DOM parts are available for styling:\n\nPart name        | Description\n-----------------|-------------------------------------------\n`backdrop`       | Backdrop of the overlay\n`overlay`        | The overlay container\n`content`        | The overlay content\n\n### Custom CSS Properties\n\nThe following custom CSS properties are available for styling:\n\nCustom CSS property                   | Description\n--------------------------------------|-------------\n`--vaadin-context-menu-offset-top`    | Used as an offset when using `position` and the context menu is aligned vertically below the target\n`--vaadin-context-menu-offset-bottom` | Used as an offset when using `position` and the context menu is aligned vertically above the target\n`--vaadin-context-menu-offset-start`  | Used as an offset when using `position` and the context menu is aligned horizontally after the target\n`--vaadin-context-menu-offset-end`    | Used as an offset when using `position` and the context menu is aligned horizontally before the target\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.\n\n### Related components\n\nIn addition to `<vaadin-context-menu>` itself, the following components are themable:\n\n- [`<vaadin-context-menu-item>`](https://cdn.vaadin.com/vaadin-web-components/25.3.0-beta1/#/elements/vaadin-context-menu-item) - an item element.\n- [`<vaadin-context-menu-list-box>`](https://cdn.vaadin.com/vaadin-web-components/25.3.0-beta1/#/elements/vaadin-context-menu-list-box) - a list-box element.",
           "extension": true,
           "attributes": [
             {
@@ -119,7 +119,7 @@
             },
             {
               "name": "@close-all-menus",
-              "description": "Fired when all menus should close, e.g., after pressing Tab or on submenu close.",
+              "description": "Fired when all menus should close, e.g., after pressing Tab or on submenu close. This event is deprecated and will be removed in Vaadin 26. Use `closed` instead.",
               "value": {
                 "kind": "expression"
               }
@@ -140,7 +140,7 @@
             },
             {
               "name": "@items-outside-click",
-              "description": "Fired when a click happens outside any open sub-menus.",
+              "description": "Fired when a click happens outside any open sub-menus. This event is deprecated and will be removed in Vaadin 26. Use `closed` instead.",
               "value": {
                 "kind": "expression"
               }