docs: custom item data for context menu and menu bar (#4158)

Co-authored-by: Russell J.T. Dyer <[email protected]>

Author: sissbruecker

articles/components/context-menu/index.adoc

@@ -3,7 +3,7 @@ tab-title: Usage
 layout: tabbed-page
 title: Context Menu
 page-title: Context Menu component | Vaadin components
-description: Context Menu is a component that you can attach to any component to display a context menu.
+description: Context Menu is a component that can be attached to any component to display a context menu.
 meta-description: Implement and configure context menus for better user interaction in your Vaadin applications.
 page-links:
   - 'API: https://cdn.vaadin.com/vaadin-web-components/{moduleNpmVersion:@vaadin/context-menu}/#/elements/vaadin-context-menu[TypeScript] / https://vaadin.com/api/platform/{moduleMavenVersion:com.vaadin:vaadin}/com/vaadin/flow/component/contextmenu/ContextMenu.html[Java]'
@@ -16,11 +16,11 @@ page-links:
 // tag::description[]
 Context Menu is a component that you can attach to any component to display a context menu.
 // end::description[]
-The menu appears on right (default) or left click. On a touch device, a long press opens the context menu.
+The menu appears on the right by default, or with a left click. On a touch device, a long press opens the context menu.
 
 // tag::example-instructions[]
 [IMPORTANT]
-Open the Context Menu by right-clicking (mouse) or long-pressing (touch) a Grid row.
+Open the Context Menu by right-clicking (i.e., with a mouse), or by long-pressing (i.e., on a touch screen), a Grid row.
 // end::example-instructions[]
 
 [.example]
@@ -52,10 +52,10 @@ include::{root}/frontend/demo/component/contextmenu/react/context-menu-basic.tsx
 endif::[]
 --
 
+
 == Dividers
 
-You can use dividers to separate and group related content.
-Use dividers sparingly to avoid creating unnecessary visual clutter.
+You can use dividers to separate and group related content. Use dividers sparingly to avoid creating unnecessary visual clutter.
 
 include::index.adoc[tag=example-instructions]
 
@@ -84,6 +84,7 @@ include::{root}/frontend/demo/component/contextmenu/react/context-menu-dividers.
 endif::[]
 --
 
+
 == Checkable Menu Items
 
 Checkable Menu Items can be used to toggle a setting on and off.
@@ -117,10 +118,10 @@ include::{root}/frontend/demo/component/contextmenu/react/context-menu-checkable
 endif::[]
 --
 
+
 == Hierarchical Menu
 
-Context Menu, like Menu Bar, supports multi-level sub-menus.
-You can use a hierarchical menu to organize a large set of options and group related items.
+Context Menu, like Menu Bar, supports multi-level sub-menus. You can use a hierarchical menu to organize a large set of options and group related items.
 
 include::index.adoc[tag=example-instructions]
 
@@ -153,6 +154,7 @@ include::{root}/frontend/demo/component/contextmenu/react/context-menu-hierarchi
 endif::[]
 --
 
+
 == Custom Items
 
 You can customize the items to include more than a single line of text.
@@ -193,6 +195,7 @@ include::{root}/frontend/demo/component/contextmenu/react/context-menu-presentat
 endif::[]
 --
 
+
 == Styling Menu Items
 
 Individual menu items can be styled by [since:com.vaadin:[email protected]]#applying custom class names# to them, and writing CSS style blocks targeting those class names.
@@ -222,9 +225,10 @@ include::{root}/frontend/demo/component/contextmenu/react/context-menu-classname
 endif::[]
 --
 
-.Use theme names instead of class names in V24.2 and older
+.Theme Names, Not Class Names
 [NOTE]
-In versions prior to 24.3, theme names must be used instead (`theme` property / `addThemeNames` Java method). The CSS syntax for targeting a theme name is `[theme~="custom-theme"]`
+In versions prior to 24.3, theme names must be used instead (i.e., `theme` property / `addThemeNames` Java method). The CSS syntax for targeting a theme name is `[theme~="custom-theme"]`
+
 
 == Disabled Menu Items
 
@@ -265,10 +269,11 @@ include::{root}/frontend/demo/component/contextmenu/react/context-menu-disabled.
 endif::[]
 --
 
+
 [role="since:com.vaadin:[email protected]"]
 === Disable on Click (Flow)
 
-To prevent duplicate clicks while the server is processing a request, call the `setDisableOnClick(true)` method on a menu item instance to immediately disable that menu item on the client-side when its clicked.
+To prevent duplicate clicks while the server is processing a request, call the `setDisableOnClick(true)` method on a menu item instance to disable immediately that menu item on the client-side when it's clicked.
 
 [.example]
 --
@@ -282,9 +287,10 @@ endif::[]
 
 --
 
+
 == Left-Click
 
-You can use left-click to open Context Menu in situations where left-click doesn't have any other function, for example a Grid without selection support.
+You can use left-click to open Context Menu in situations where left-click doesn't have any other function (e.g., a Grid without selection support).
 
 [IMPORTANT]
 Open the Context Menu by clicking a Grid row.
@@ -318,14 +324,43 @@ include::{root}/frontend/demo/component/contextmenu/react/context-menu-left-clic
 endif::[]
 --
 
+
+[role="since:com.vaadin:[email protected]"]
+== Custom Item Data
+
+Context Menu allows you to associate custom data with menu items. This can be useful for storing additional information about the item, such as an item type or a value. The data can then be used to trigger actions when an item is selected.
+
+[.example]
+--
+ifdef::lit[]
+[source,typescript]
+----
+include::{root}/frontend/demo/component/contextmenu/context-menu-custom-item-data.ts[render,tags=snippet,indent=0,group=Lit]
+----
+endif::[]
+
+ifdef::flow[]
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/component/contextmenu/ContextMenuCustomItemData.java[render,tags=snippet,indent=0,group=Flow]
+----
+endif::[]
+
+ifdef::react[]
+[source,tsx]
+----
+include::{root}/frontend/demo/component/contextmenu/react/context-menu-custom-item-data.tsx[render,tags=snippet,indent=0,group=React]
+----
+endif::[]
+--
+
+
 == Best Practices
 
-Context Menu is used to provide shortcuts to the user.
-You shouldn't use it as the only or primary means to complete a task.
-The primary way should be accessible elsewhere in the UI.
+Context Menu is used to provide shortcuts to the user. You shouldn't use it as the only or primary means to complete a task. The primary way should be accessible elsewhere in the UI.
 
 [IMPORTANT]
-Open the Context Menu by right-clicking (desktop) or long-pressing (mobile) a Grid row, or use the Menu Bar in the last column.
+Open the Context Menu by right-clicking (i.e., for desktops) or long-pressing (i.e., for mobile devices) a Grid row, or use the Menu Bar in the last column.
 
 [.example]
 --
@@ -356,26 +391,26 @@ include::{root}/frontend/demo/component/contextmenu/react/context-menu-best-prac
 endif::[]
 --
 
-=== Context Menu vs Menu Bar
 
-You should use Context Menu when there is no dedicated button for opening an overlay menu, such as right-clicking a grid row.
-When there is a dedicated element/component, such as an <<../menu-bar#,overflow menu>>, use Menu Bar.
+=== Context Menu vs. Menu Bar
+
+You should use Context Menu when there is no dedicated button for opening an overlay menu, such as right-clicking a grid row. When there is a dedicated element or component, such as an <<../menu-bar#,overflow menu>>, use Menu Bar.
+
 
 === Icons
 
-Use icons when applicable to help improve recognition.
-It's recommended to use commonly recognized icons to avoid confusion.
-Use icons consistently throughout a list of options.
+Use icons when applicable to help improve recognition. It's recommended to use commonly recognized icons to avoid confusion. Use icons consistently throughout a list of options.
+
 
 === Labelling
 
-Suffix a menu item with “...” when the associated action won't be executed, but instead reveal some UI, like a dialog, for completing the action.
+Suffix a menu item with "..." when the associated action won't be executed, but instead reveal some UI, like a dialog, for completing the action.
 
 
 == Related Components
 
 |===
-|Component |Usage recommendations
+|Component |Usage Recommendations
 
 |<<../menu-bar#,Menu Bar>>
 |Component for displaying a horizontal menu with multi-level sub-menus.

articles/components/menu-bar/index.adoc

@@ -615,7 +615,36 @@ endif::[]
 ifdef::react[]
 [source,tsx]
 ----
-include::{root}/frontend/demo/component/menubar/react/menu-bar-internationalization.tsx[render,tags=snippet,indent=0,group=React]
+include::{root}/frontend/demo/component/menubar/react/menu-bar-internationalization.tsx[tags=snippet,indent=0,group=React]
+----
+endif::[]
+--
+
+[role="since:com.vaadin:[email protected]"]
+== Custom Item Data
+
+Menu Bar allows you to associate custom data with menu items. This can be useful for storing additional information about the item, such as an item type or a value. The data can then be used to trigger actions when an item is selected.
+
+[.example]
+--
+ifdef::lit[]
+[source,typescript]
+----
+include::{root}/frontend/demo/component/menubar/menu-bar-custom-item-data.ts[render,tags=snippet,indent=0,group=Lit]
+----
+endif::[]
+
+ifdef::flow[]
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/component/menubar/MenuBarCustomItemData.java[render,tags=snippet,indent=0,group=Flow]
+----
+endif::[]
+
+ifdef::react[]
+[source,tsx]
+----
+include::{root}/frontend/demo/component/menubar/react/menu-bar-custom-item-data.tsx[render,tags=snippet,indent=0,group=React]
 ----
 endif::[]
 --

frontend/demo/component/contextmenu/context-menu-custom-item-data.ts

@@ -0,0 +1,57 @@
+import 'Frontend/demo/init'; // hidden-source-line
+import '@vaadin/context-menu';
+import { html, LitElement } from 'lit';
+import { customElement, state } from 'lit/decorators.js';
+import type { ContextMenuItem, ContextMenuItemSelectedEvent } from '@vaadin/context-menu';
+import { applyTheme } from 'Frontend/generated/theme';
+
+@customElement('context-menu-custom-item-data')
+export class Example extends LitElement {
+  protected override createRenderRoot() {
+    const root = super.createRenderRoot();
+    // Apply custom theme (only supported if your app uses one)
+    applyTheme(root);
+    return root;
+  }
+
+  // tag::snippet[]
+  @state()
+  private items: Array<ContextMenuItem<{ value: string }>> = [
+    {
+      text: 'Copy as plain text',
+      value:
+        'Context Menu\n\nContext Menu is a component that you can attach to any component to display a context menu.',
+    },
+    {
+      text: 'Copy as HTML',
+      value:
+        '<h1>Context Menu</h1><p>Context Menu is a component that you can attach to any component to display a context menu.</p>',
+    },
+    {
+      text: 'Copy as Markdown',
+      value:
+        '# Context Menu\n\nContext Menu is a component that you can attach to any component to display a context menu.',
+    },
+  ];
+
+  protected override render() {
+    return html`
+      <vaadin-context-menu .items="${this.items}" @item-selected="${this.itemSelected}">
+        <h1>Context Menu</h1>
+        <p>
+          Context Menu is a component that you can attach to any component to display a context
+          menu.
+        </p>
+      </vaadin-context-menu>
+    `;
+  }
+
+  itemSelected(e: ContextMenuItemSelectedEvent<ContextMenuItem<{ value?: string }>>) {
+    const value = e.detail.value.value;
+    if (value) {
+      navigator.clipboard.writeText(value);
+    }
+  }
+
+  // end::snippet[]
+}

frontend/demo/component/contextmenu/react/context-menu-custom-item-data.tsx

@@ -0,0 +1,44 @@
+import { reactExample } from 'Frontend/demo/react-example'; // hidden-source-line
+import React from 'react';
+import { ContextMenu, type ContextMenuItem } from '@vaadin/react-components';
+
+function Example() {
+  // tag::snippet[]
+  const items: Array<ContextMenuItem<{ value: string }>> = [
+    {
+      text: 'Copy as plain text',
+      value:
+        'Context Menu\n\nContext Menu is a component that you can attach to any component to display a context menu.',
+    },
+    {
+      text: 'Copy as HTML',
+      value:
+        '<h1>Context Menu</h1><p>Context Menu is a component that you can attach to any component to display a context menu.</p>',
+    },
+    {
+      text: 'Copy as Markdown',
+      value:
+        '# Context Menu\n\nContext Menu is a component that you can attach to any component to display a context menu.',
+    },
+  ];
+
+  return (
+    <ContextMenu
+      items={items}
+      onItemSelected={(event) => {
+        const value = event.detail.value.value;
+        if (value) {
+          navigator.clipboard.writeText(value);
+        }
+      }}
+    >
+      <h1>Context Menu</h1>
+      <p>
+        Context Menu is a component that you can attach to any component to display a context menu.
+      </p>
+    </ContextMenu>
+  );
+  // end::snippet[]
+}
+
+export default reactExample(Example); // hidden-source-line

frontend/demo/component/menubar/menu-bar-custom-item-data.ts

@@ -0,0 +1,58 @@
+import 'Frontend/demo/init'; // hidden-source-line
+import '@vaadin/menu-bar';
+import { html, LitElement } from 'lit';
+import { customElement, state } from 'lit/decorators.js';
+import type { MenuBarItem, MenuBarItemSelectedEvent } from '@vaadin/menu-bar';
+import { applyTheme } from 'Frontend/generated/theme';
+
+@customElement('menu-bar-custom-item-data')
+export class Example extends LitElement {
+  protected override createRenderRoot() {
+    const root = super.createRenderRoot();
+    // Apply custom theme (only supported if your app uses one)
+    applyTheme(root);
+    return root;
+  }
+
+  // tag::snippet[]
+  @state()
+  private items: Array<MenuBarItem<{ value?: string }>> = [
+    {
+      text: 'Copy',
+      children: [
+        {
+          text: 'Copy as plain text',
+          value:
+            'Menu Bar\n\nMenu Bar is a horizontal button bar with hierarchical drop-down menus.',
+        },
+        {
+          text: 'Copy as HTML',
+          value:
+            '<h1>Menu Bar</h1><p>Menu Bar is a horizontal button bar with hierarchical drop-down menus.</p>',
+        },
+        {
+          text: 'Copy as Markdown',
+          value:
+            '# Menu Bar\n\nMenu Bar is a horizontal button bar with hierarchical drop-down menus.',
+        },
+      ],
+    },
+  ];
+
+  protected override render() {
+    return html`
+      <vaadin-menu-bar
+        .items="${this.items}"
+        @item-selected="${this.itemSelected}"
+      ></vaadin-menu-bar>
+    `;
+  }
+
+  itemSelected(e: MenuBarItemSelectedEvent<MenuBarItem<{ value?: string }>>) {
+    const value = e.detail.value.value;
+    if (value) {
+      navigator.clipboard.writeText(value);
+    }
+  }
+  // end::snippet[]
+}