@vaadin/context-menu 25.3.0-alpha6 → 25.3.0-dev.1fa5a51482

package/web-types.lit.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/context-menu",
-  "version": "25.3.0-alpha6",
+  "version": "25.3.0-dev.1fa5a51482",
   "description-markup": "markdown",
   "framework": "lit",
   "framework-config": {
@@ -14,9 +14,58 @@
   "contributions": {
     "html": {
       "elements": [
+        {
+          "name": "vaadin-context-menu-item",
+          "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.",
+          "extension": true,
+          "attributes": [
+            {
+              "name": "?disabled",
+              "description": "If true, the user cannot interact with this element.",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": "?selected",
+              "description": "If true, the item is in selected state.",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": ".value",
+              "description": "Submittable string value. The default value is the trimmed text content of the element.",
+              "value": {
+                "kind": "expression"
+              }
+            }
+          ]
+        },
+        {
+          "name": "vaadin-context-menu-list-box",
+          "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.",
+          "extension": true,
+          "attributes": [
+            {
+              "name": "?disabled",
+              "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.",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": ".selected",
+              "description": "The index of the item selected in the items array.\nNote: Not updated when used in `multiple` selection mode.",
+              "value": {
+                "kind": "expression"
+              }
+            }
+          ]
+        },
         {
           "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### 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>`](https://cdn.vaadin.com/vaadin-web-components/25.3.0-alpha6/#/elements/vaadin-item).\n- `<vaadin-context-menu-list-box>` - has the same API as [`<vaadin-list-box>`](https://cdn.vaadin.com/vaadin-web-components/25.3.0-alpha6/#/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>`](https://cdn.vaadin.com/vaadin-web-components/25.3.0-dev.1fa5a51482/#/elements/vaadin-context-menu-item) - an item element.\n- [`<vaadin-context-menu-list-box>`](https://cdn.vaadin.com/vaadin-web-components/25.3.0-dev.1fa5a51482/#/elements/vaadin-context-menu-list-box) - a list-box element.",
           "extension": true,
           "attributes": [
             {