@vaadin/context-menu 25.3.0-alpha1 → 25.3.0-alpha10

package/custom-elements.json

@@ -17,6 +17,316 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "vaadin-context-menu-list-box.js",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "module": "src/vaadin-context-menu-list-box.js"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "vaadin-context-menu-item.js",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "module": "src/vaadin-context-menu-item.js"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/vaadin-context-menu-item.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "`<vaadin-context-menu-item>` is a Web Component for creating `<vaadin-context-menu>` items.\n\n### Styling\n\nThe following shadow DOM parts are available for styling:\n\nPart name    | Description\n-------------|----------------\n`checkmark`  | The graphical checkmark shown for a checked item\n`content`    | The element that wraps the slot\n\nThe following state attributes are available for styling:\n\nAttribute    | Description\n-------------|-------------\n`active`     | Set when the item is pressed down, either with mouse, touch or the keyboard.\n`disabled`   | Set when the item is disabled.\n`focus-ring` | Set when the item is focused using the keyboard.\n`focused`    | Set when the item is focused.\n`expanded`   | Set when the item has a sub-menu and it is opened.\n\nThe following custom CSS properties are available for styling:\n\nCustom CSS property                |\n:----------------------------------|\n| `--vaadin-item-border-radius`    |\n| `--vaadin-item-checkmark-color`  |\n| `--vaadin-item-gap`              |\n| `--vaadin-item-height`           |\n| `--vaadin-item-padding`          |\n| `--vaadin-item-text-align`       |\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.",
+          "name": "ContextMenuItem",
+          "members": [
+            {
+              "kind": "field",
+              "name": "disabled",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "If true, the user cannot interact with this element.",
+              "attribute": "disabled",
+              "inheritedFrom": {
+                "name": "DisabledMixin",
+                "package": "@vaadin/a11y-base/src/disabled-mixin.js"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "selected",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "If true, the item is in selected state.",
+              "attribute": "selected",
+              "inheritedFrom": {
+                "name": "ItemMixin",
+                "package": "@vaadin/item/src/vaadin-item-mixin.js"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "value",
+              "description": "Submittable string value. The default value is the trimmed text content of the element.",
+              "type": {
+                "text": "string"
+              },
+              "inheritedFrom": {
+                "name": "ItemMixin",
+                "package": "@vaadin/item/src/vaadin-item-mixin.js"
+              }
+            }
+          ],
+          "attributes": [
+            {
+              "name": "disabled",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "If true, the user cannot interact with this element.",
+              "fieldName": "disabled",
+              "inheritedFrom": {
+                "name": "DisabledMixin",
+                "package": "@vaadin/a11y-base/src/disabled-mixin.js"
+              }
+            },
+            {
+              "name": "selected",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "If true, the item is in selected state.",
+              "fieldName": "selected",
+              "inheritedFrom": {
+                "name": "ItemMixin",
+                "package": "@vaadin/item/src/vaadin-item-mixin.js"
+              }
+            },
+            {
+              "type": {
+                "text": "string"
+              },
+              "description": "The theme variants to apply to the component.",
+              "name": "theme"
+            }
+          ],
+          "mixins": [
+            {
+              "name": "ItemMixin",
+              "package": "@vaadin/item/src/vaadin-item-mixin.js"
+            },
+            {
+              "name": "ThemableMixin",
+              "package": "@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js"
+            },
+            {
+              "name": "DirMixin",
+              "package": "@vaadin/component-base/src/dir-mixin.js"
+            },
+            {
+              "name": "PolylitMixin",
+              "package": "@vaadin/component-base/src/polylit-mixin.js"
+            },
+            {
+              "name": "LumoInjectionMixin",
+              "package": "@vaadin/vaadin-themable-mixin/lumo-injection-mixin.js"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "vaadin-context-menu-item",
+          "customElement": true,
+          "events": []
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "ContextMenuItem",
+          "declaration": {
+            "name": "ContextMenuItem",
+            "module": "src/vaadin-context-menu-item.js"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/vaadin-context-menu-list-box.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "`<vaadin-context-menu-list-box>` is a Web Component for wrapping `<vaadin-context-menu>` items.\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### Styling\n\nThe following shadow DOM parts are available for styling:\n\nPart name         | Description\n------------------|------------------------\n`items`           | The items container\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.",
+          "name": "ContextMenuListBox",
+          "members": [
+            {
+              "kind": "field",
+              "name": "disabled",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "If true, the user cannot interact with this element.\nWhen the element is disabled, the selected item is\nnot updated when `selected` property is changed.",
+              "attribute": "disabled",
+              "inheritedFrom": {
+                "name": "ListMixin",
+                "package": "@vaadin/a11y-base/src/list-mixin.js"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "items",
+              "privacy": "public",
+              "type": {
+                "text": "!Array<!Element> | undefined"
+              },
+              "description": "A read-only list of items from which a selection can be made.\nIt is populated from the elements passed to the light DOM,\nand updated dynamically when adding or removing items.",
+              "attribute": "items",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "ListMixin",
+                "package": "@vaadin/a11y-base/src/list-mixin.js"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "orientation",
+              "privacy": "public",
+              "type": {
+                "text": "string"
+              },
+              "description": "Define how items are disposed in the dom.\nPossible values are: `horizontal|vertical`.\nIt also changes navigation keys from left/right to up/down.",
+              "attribute": "orientation",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "ListMixin",
+                "package": "@vaadin/a11y-base/src/list-mixin.js"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "selected",
+              "privacy": "public",
+              "type": {
+                "text": "number"
+              },
+              "description": "The index of the item selected in the items array.\nNote: Not updated when used in `multiple` selection mode.",
+              "attribute": "selected",
+              "inheritedFrom": {
+                "name": "ListMixin",
+                "package": "@vaadin/a11y-base/src/list-mixin.js"
+              }
+            }
+          ],
+          "attributes": [
+            {
+              "name": "disabled",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "If true, the user cannot interact with this element.\nWhen the element is disabled, the selected item is\nnot updated when `selected` property is changed.",
+              "fieldName": "disabled",
+              "inheritedFrom": {
+                "name": "ListMixin",
+                "package": "@vaadin/a11y-base/src/list-mixin.js"
+              }
+            },
+            {
+              "name": "orientation",
+              "type": {
+                "text": "string"
+              },
+              "description": "Define how items are disposed in the dom.\nPossible values are: `horizontal|vertical`.\nIt also changes navigation keys from left/right to up/down.",
+              "fieldName": "orientation",
+              "inheritedFrom": {
+                "name": "ListMixin",
+                "package": "@vaadin/a11y-base/src/list-mixin.js"
+              }
+            },
+            {
+              "name": "selected",
+              "type": {
+                "text": "number"
+              },
+              "description": "The index of the item selected in the items array.\nNote: Not updated when used in `multiple` selection mode.",
+              "fieldName": "selected",
+              "inheritedFrom": {
+                "name": "ListMixin",
+                "package": "@vaadin/a11y-base/src/list-mixin.js"
+              }
+            },
+            {
+              "type": {
+                "text": "string"
+              },
+              "description": "The theme variants to apply to the component.",
+              "name": "theme"
+            }
+          ],
+          "mixins": [
+            {
+              "name": "ListMixin",
+              "package": "@vaadin/a11y-base/src/list-mixin.js"
+            },
+            {
+              "name": "ThemableMixin",
+              "package": "@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js"
+            },
+            {
+              "name": "DirMixin",
+              "package": "@vaadin/component-base/src/dir-mixin.js"
+            },
+            {
+              "name": "PolylitMixin",
+              "package": "@vaadin/component-base/src/polylit-mixin.js"
+            },
+            {
+              "name": "LumoInjectionMixin",
+              "package": "@vaadin/vaadin-themable-mixin/lumo-injection-mixin.js"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "vaadin-context-menu-list-box",
+          "customElement": true,
+          "events": []
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "ContextMenuListBox",
+          "declaration": {
+            "name": "ContextMenuListBox",
+            "module": "src/vaadin-context-menu-list-box.js"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/vaadin-context-menu-mixin.js",
@@ -50,7 +360,7 @@
               "name": "items",
               "privacy": "public",
               "type": {
-                "text": "!Array<!ContextMenuItem> | undefined"
+                "text": "!Array<!ContextMenuItemData> | undefined"
               },
               "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', 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```\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```",
               "attribute": "items",
@@ -113,6 +423,7 @@
                 "text": "ContextMenuRenderer | undefined"
               },
               "description": "Custom function for rendering the content of the menu overlay.\nReceives three arguments:\n\n- `root` The root container DOM element. Append your content to it.\n- `contextMenu` The reference to the `<vaadin-context-menu>` element.\n- `context` The object with the menu context, contains:\n  - `context.target`  the target of the menu opening event,\n  - `context.detail` the menu opening event detail.",
+              "deprecated": "Use a slotted `<vaadin-context-menu-list-box>` or the `items` property instead",
               "attribute": "renderer"
             },
             {
@@ -157,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": [
@@ -199,6 +520,7 @@
                 "text": "ContextMenuRenderer | undefined"
               },
               "description": "Custom function for rendering the content of the menu overlay.\nReceives three arguments:\n\n- `root` The root container DOM element. Append your content to it.\n- `contextMenu` The reference to the `<vaadin-context-menu>` element.\n- `context` The object with the menu context, contains:\n  - `context.target`  the target of the menu opening event,\n  - `context.detail` the menu opening event detail.",
+              "deprecated": "Use a slotted `<vaadin-context-menu-list-box>` or the `items` property instead",
               "fieldName": "renderer"
             },
             {
@@ -319,7 +641,7 @@
       "declarations": [
         {
           "kind": "class",
-          "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### 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### Internal components\n\nWhen using `items` API the following internal components are themable:\n\n- `<vaadin-context-menu-item>` - has the same API as [`<vaadin-item>`](#/elements/vaadin-item).\n- `<vaadin-context-menu-list-box>` - has the same API as [`<vaadin-list-box>`](#/elements/vaadin-list-box).\n\nThe `<vaadin-context-menu-item>` sub-menu elements have the following additional state attributes\non top of the built-in `<vaadin-item>` state attributes:\n\nAttribute  | Description\n---------- |-------------\n`expanded` | Expanded parent item.",
+          "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>`](#/elements/vaadin-context-menu-item) - an item element.\n- [`<vaadin-context-menu-list-box>`](#/elements/vaadin-context-menu-list-box) - a list-box element.",
           "name": "ContextMenu",
           "members": [
             {
@@ -350,7 +672,7 @@
               "name": "items",
               "privacy": "public",
               "type": {
-                "text": "!Array<!ContextMenuItem> | undefined"
+                "text": "!Array<!ContextMenuItemData> | undefined"
               },
               "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', 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```\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```",
               "attribute": "items",
@@ -439,6 +761,7 @@
                 "text": "ContextMenuRenderer | undefined"
               },
               "description": "Custom function for rendering the content of the menu overlay.\nReceives three arguments:\n\n- `root` The root container DOM element. Append your content to it.\n- `contextMenu` The reference to the `<vaadin-context-menu>` element.\n- `context` The object with the menu context, contains:\n  - `context.target`  the target of the menu opening event,\n  - `context.detail` the menu opening event detail.",
+              "deprecated": "Use a slotted `<vaadin-context-menu-list-box>` or the `items` property instead",
               "attribute": "renderer",
               "inheritedFrom": {
                 "name": "ContextMenuMixin",
@@ -475,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"
@@ -504,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": {
@@ -582,6 +909,7 @@
                 "text": "ContextMenuRenderer | undefined"
               },
               "description": "Custom function for rendering the content of the menu overlay.\nReceives three arguments:\n\n- `root` The root container DOM element. Append your content to it.\n- `contextMenu` The reference to the `<vaadin-context-menu>` element.\n- `context` The object with the menu context, contains:\n  - `context.target`  the target of the menu opening event,\n  - `context.detail` the menu opening event detail.",
+              "deprecated": "Use a slotted `<vaadin-context-menu-list-box>` or the `items` property instead",
               "fieldName": "renderer",
               "inheritedFrom": {
                 "name": "ContextMenuMixin",
@@ -599,6 +927,13 @@
                 "name": "ContextMenuMixin",
                 "module": "src/vaadin-context-menu-mixin.js"
               }
+            },
+            {
+              "type": {
+                "text": "string"
+              },
+              "description": "The theme variants to apply to the component.",
+              "name": "theme"
             }
           ],
           "mixins": [
@@ -656,7 +991,7 @@
               "name": "items",
               "privacy": "public",
               "type": {
-                "text": "!Array<!ContextMenuItem> | undefined"
+                "text": "!Array<!ContextMenuItemData> | undefined"
               },
               "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', 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```\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```",
               "attribute": "items"
@@ -674,6 +1009,12 @@
               "type": {
                 "text": "CustomEvent"
               }
+            },
+            {
+              "name": "items-outside-click",
+              "type": {
+                "text": "CustomEvent"
+              }
             }
           ],
           "attributes": [],
@@ -704,6 +1045,20 @@
           "description": "",
           "name": "MenuOverlayMixin",
           "members": [
+            {
+              "kind": "field",
+              "name": "autofocus",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Set to true to move focus into the overlay automatically on open.\n\nFocus moves to the first tabbable element in the tab order. This\ncan be the overlay itself if it has `tabindex` attribute set to `0`\non the host element or the `overlay` shadow DOM part.",
+              "attribute": "autofocus",
+              "inheritedFrom": {
+                "name": "OverlayFocusMixin",
+                "package": "@vaadin/overlay/src/vaadin-overlay-focus-mixin.js"
+              }
+            },
             {
               "kind": "field",
               "name": "focusTrap",
@@ -711,7 +1066,7 @@
               "type": {
                 "text": "boolean"
               },
-              "description": "When true, opening the overlay moves focus to the first focusable child,\nor to the overlay part with tabindex if there are no focusable children.",
+              "description": "Set to true to move focus into the overlay automatically on open\nand keep it inside: Tab and Shift+Tab cycle through the overlay's\ncontent until the overlay is closed.\n\nFocus moves to the first tabbable element in the tab order. This\ncan be the overlay itself if it has `tabindex` attribute set to `0`\non the host element or the `overlay` shadow DOM part.",
               "attribute": "focus-trap",
               "inheritedFrom": {
                 "name": "OverlayFocusMixin",
@@ -842,12 +1197,24 @@
             }
           ],
           "attributes": [
+            {
+              "name": "autofocus",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Set to true to move focus into the overlay automatically on open.\n\nFocus moves to the first tabbable element in the tab order. This\ncan be the overlay itself if it has `tabindex` attribute set to `0`\non the host element or the `overlay` shadow DOM part.",
+              "fieldName": "autofocus",
+              "inheritedFrom": {
+                "name": "OverlayFocusMixin",
+                "package": "@vaadin/overlay/src/vaadin-overlay-focus-mixin.js"
+              }
+            },
             {
               "name": "focus-trap",
               "type": {
                 "text": "boolean"
               },
-              "description": "When true, opening the overlay moves focus to the first focusable child,\nor to the overlay part with tabindex if there are no focusable children.",
+              "description": "Set to true to move focus into the overlay automatically on open\nand keep it inside: Tab and Shift+Tab cycle through the overlay's\ncontent until the overlay is closed.\n\nFocus moves to the first tabbable element in the tab order. This\ncan be the overlay itself if it has `tabindex` attribute set to `0`\non the host element or the `overlay` shadow DOM part.",
               "fieldName": "focusTrap",
               "inheritedFrom": {
                 "name": "OverlayFocusMixin",

package/package.json

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

package/src/lit/renderer-directives.d.ts

@@ -52,6 +52,7 @@ export class ContextMenuRendererDirective extends LitRendererDirective<ContextMe
  * @param renderer the renderer callback that returns a Lit template.
  * @param dependencies a single dependency or an array of dependencies
  *                     which trigger a re-render when changed.
+ * @deprecated Use a slotted `<vaadin-context-menu-list-box>` or the `items` property instead
  */
 export declare function contextMenuRenderer(
   renderer: ContextMenuLitRenderer,

package/src/lit/renderer-directives.js

@@ -56,5 +56,6 @@ export class ContextMenuRendererDirective extends LitRendererDirective {
  * @param renderer the renderer callback that returns a Lit template.
  * @param dependencies a single dependency or an array of dependencies
  *                     which trigger a re-render when changed.
+ * @deprecated Use a slotted `<vaadin-context-menu-list-box>` or the `items` property instead
  */
 export const contextMenuRenderer = directive(ContextMenuRendererDirective);

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

@@ -8,7 +8,39 @@ import { ItemMixin } from '@vaadin/item/src/vaadin-item-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 
 /**
- * An element used internally by `<vaadin-context-menu>`. Not intended to be used separately.
+ * `<vaadin-context-menu-item>` is a Web Component for creating `<vaadin-context-menu>` items.
+ *
+ * ### Styling
+ *
+ * The following shadow DOM parts are available for styling:
+ *
+ * Part name    | Description
+ * -------------|----------------
+ * `checkmark`  | The graphical checkmark shown for a checked item
+ * `content`    | The element that wraps the slot
+ *
+ * The following state attributes are available for styling:
+ *
+ * Attribute    | Description
+ * -------------|-------------
+ * `active`     | Set when the item is pressed down, either with mouse, touch or the keyboard.
+ * `disabled`   | Set when the item is disabled.
+ * `focus-ring` | Set when the item is focused using the keyboard.
+ * `focused`    | Set when the item is focused.
+ * `expanded`   | Set when the item has a sub-menu and it is opened.
+ *
+ * The following custom CSS properties are available for styling:
+ *
+ * Custom CSS property                |
+ * :----------------------------------|
+ * | `--vaadin-item-border-radius`    |
+ * | `--vaadin-item-checkmark-color`  |
+ * | `--vaadin-item-gap`              |
+ * | `--vaadin-item-height`           |
+ * | `--vaadin-item-padding`          |
+ * | `--vaadin-item-text-align`       |
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  */
 declare class ContextMenuItem extends ItemMixin(DirMixin(ThemableMixin(HTMLElement))) {}