docs: update MenuBar docs to use CSS class (#3048)

* docs: update MenuBar docs to use CSS class

* docs: fix grammar

* refactor: use lumo utility classes for styling

* Initial edits and Vale fixes.

* Vale fix.

* Second pass at editing.

---------

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

articles/components/menu-bar/index.adoc

@@ -35,7 +35,6 @@ include::{root}/src/main/java/com/vaadin/demo/component/menubar/MenuBarBasic.jav
 ----
 endif::[]
 
-
 ifdef::react[]
 [source,tsx]
 ----
@@ -44,6 +43,7 @@ include::{root}/frontend/demo/component/menubar/react/menu-bar-basic.tsx[render,
 endif::[]
 --
 
+
 == Styles
 
 === Default Variants
@@ -83,7 +83,7 @@ endif::[]
 |Corresponds to the <<../button#styles,tertiary button variant>>, omitting the background color.
 
 |Primary
-|Corresponds to the primary button variant. As only one primary action should be presented in the same part of the UI, this should be used only for <<dropdown-buttons,drop-down button use cases>>.
+|Corresponds to the primary button variant. Since only one primary action should be presented in the same part of the UI, this should be used only for <<dropdown-buttons,drop-down button use cases>>.
 
 |Small
 |Compact variant. Can be combined with Tertiary and Primary.
@@ -123,48 +123,46 @@ include::{root}/frontend/demo/component/menubar/react/menu-bar-right-aligned.tsx
 endif::[]
 --
 
-=== Styling Menu Items
 
-An individual menu item can be styled using custom theme variants. A custom variant can be created by adding a custom theme name (e.g., `custom-theme`) to an item, and then adding CSS for styling all items using that theme name.
+=== Styling Menu Items
 
-The following example shows how to add a custom theme variant named `custom-theme` to individual menu bar buttons and items, and how to style that variant with CSS:
+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. Notice that root-level menu items in the Menu Bar are wrapped in `vaadin-menu-bar-button` elements, which inherit the class names from the items within them.
 
 [.example]
 --
 
 ifdef::lit[]
 [source,typescript]
 ----
-include::{root}/frontend/demo/component/menubar/menu-bar-custom-theme.ts[render,tags=snippet,indent=0,group=TypeScript]
+include::{root}/frontend/demo/component/menubar/menu-bar-custom-styling.ts[render,tags=snippet,indent=0,group=TypeScript]
 ----
 endif::[]
 
 ifdef::flow[]
 [source,java]
 ----
-include::{root}/src/main/java/com/vaadin/demo/component/menubar/MenuBarCustomTheme.java[render,tags=snippet,indent=0,group=Java]
+include::{root}/src/main/java/com/vaadin/demo/component/menubar/MenuBarCustomStyling.java[render,tags=snippet,indent=0,group=Java]
 ----
 endif::[]
-
-[source,css]
-----
-include::{root}/frontend/themes/docs/menu-bar-theming.css[]
 ----
 
 
 ifdef::react[]
 [source,tsx]
 ----
-include::{root}/frontend/demo/component/menubar/react/menu-bar-custom-theme.tsx[render,tags=snippet,indent=0,group=React]
+include::{root}/frontend/demo/component/menubar/react/menu-bar-custom-styling.tsx[render,tags=snippet,indent=0,group=React]
 ----
 endif::[]
 --
 
+.Use Theme Names, Not Class Names pre-V24.3
+[NOTE]
+In versions prior to 24.3, theme names must be used instead  of class names (`theme` property / `addThemeNames` Java method). The CSS syntax for targeting a theme name is `[theme~="custom-theme"]`
 
 
 == Overflow
 
-Items that don't fit into the current width of the menu bar collapse automatically into an overflow menu at the end:
+Items that don't fit into the current width of the menu bar collapse into an overflow menu at the end:
 
 [.example]
 --
@@ -193,14 +191,10 @@ endif::[]
 --
 
 
-
 == Menu Item Features
 
-pass:[<!-- vale Vaadin.ThereIs = NO -->]
-
-There are several features available for menu items. They're described in the following sub-sections.
+Several features are available for menu items. They're described in the following sub-sections.
 
-pass:[<!-- vale Vaadin.ThereIs = YES -->]
 
 === Icons
 
@@ -304,6 +298,7 @@ include::{root}/frontend/demo/component/menubar/react/menu-bar-disabled.tsx[rend
 endif::[]
 --
 
+
 === Checkable Menu Items
 
 Menu items in drop-down menus can be configured as checkable to toggle options on and off.
@@ -339,7 +334,6 @@ endif::[]
 A Menu Bar with checkable items shouldn't be used as a replacement for <<../radio-button#,radio buttons>> in a form.
 
 
-
 == Dividers
 
 You can use dividers to separate and group related content. However, use dividers sparingly to avoid creating unnecessary visual clutter.
@@ -375,7 +369,6 @@ endif::[]
 While it's technically possible to put any UI element in a drop-down menu -- including interactive components -- they're not accessible by keyboard or assistive technologies.
 
 
-
 == Open on Hover
 
 A component can be configured to open drop-down menus on hover, instead of on click.
@@ -397,7 +390,6 @@ include::{root}/src/main/java/com/vaadin/demo/component/menubar/MenuBarOpenOnHov
 ----
 endif::[]
 
-
 ifdef::react[]
 [source,tsx]
 ----
@@ -407,7 +399,6 @@ endif::[]
 --
 
 
-
 [role="since:com.vaadin:[email protected]"]
 == Tooltips
 
@@ -449,7 +440,6 @@ endif::[]
 See the <<../tooltip#,Tooltips documentation page>> for details on tooltip configuration.
 
 
-
 == Keyboard Usage
 
 === Top-Level Items
@@ -550,7 +540,6 @@ endif::[]
 --
 
 
-
 == Internationalization (i18n)
 
 Menu Bar provides an API for localization. Currently, only the accessible label for the overflow menu button can be customized.
@@ -580,7 +569,6 @@ endif::[]
 --
 
 
-
 == Best Practices
 
 Menu Bar shouldn't be used for navigation. Use <<../tabs#,tabs>> to switch between content, or anchor elements for regular navigation. It isn't an input field. Use instead <<../select#,Select>>, <<../combo-box#,Combo Box>>, or <<../radio-button#,Radio Button>>.
@@ -606,7 +594,6 @@ Menu Bar is an interactive component. Using other interactive components like Co
 |A generic drop-down menu that can be triggered from any component.
 |===
 
-
 [discussion-id]`BCC76FD2-FB02-4F71-A6DF-7574CAC1C662`
 
 ++++

articles/components/message-list/index.asciidoc → articles/components/message-list/index.adoc

@@ -39,14 +39,12 @@ include::{root}/frontend/demo/component/messages/react/message-list-component.ts
 endif::[]
 --
 
-The messages in the list can be populated with the `items` property.
-The `items` property is of type [classname]`Array`, with JSON objects in it.
-Each JSON object is a single message.
+The messages in the list can be populated with the `items` property. The `items` property is of type [classname]`Array`, with JSON objects in it. Each JSON object is a single message.
+
 
 == Styling
 
-You can style individual messages by adding a theme property to some items and providing CSS for that theme.
-The following example shows how to highlight the current user's own messages:
+You can style individual messages by adding a theme property to some items and providing CSS for that theme. The following example shows how to highlight the current user's own messages:
 
 [.example]
 --
@@ -75,9 +73,9 @@ include::{root}/frontend/demo/component/messages/react/message-list-with-theme-c
 endif::[]
 --
 
-.Use theme names instead of classnames in V24.2 and older
+.Use Theme Names, Not Class Names pre-V24.3
 [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 of class names (`theme` property / `addThemeNames` Java method). The CSS syntax for targeting a theme name is `[theme~="custom-theme"]`.
 
 
 == Related Components

frontend/demo/component/menubar/menu-bar-custom-theme.ts → frontend/demo/component/menubar/menu-bar-custom-styling.ts

@@ -5,7 +5,7 @@ import { customElement, state } from 'lit/decorators.js';
 import '@vaadin/menu-bar';
 import { applyTheme } from 'Frontend/generated/theme';
 
-@customElement('menu-bar-custom-theme')
+@customElement('menu-bar-custom-styling')
 export class Example extends LitElement {
   protected override createRenderRoot() {
     const root = super.createRenderRoot();
@@ -17,11 +17,14 @@ export class Example extends LitElement {
   // tag::snippet[]
   @state()
   private accessor items = [
-    { text: 'View', theme: 'custom-theme' },
+    { text: 'View', className: 'bg-primary text-primary-contrast' },
     { text: 'Edit' },
     {
       text: 'Share',
-      children: [{ text: 'By email', theme: 'custom-theme' }, { text: 'Get link' }],
+      children: [
+        { text: 'By email', className: 'bg-primary text-primary-contrast' },
+        { text: 'Get link' },
+      ],
     },
   ];
 

frontend/demo/component/menubar/react/menu-bar-custom-theme.tsx → frontend/demo/component/menubar/react/menu-bar-custom-styling.tsx

@@ -5,11 +5,14 @@ import { MenuBar } from '@hilla/react-components/MenuBar.js';
 function Example() {
   // tag::snippet[]
   const items = [
-    { text: 'View', theme: 'custom-theme' },
+    { text: 'View', className: 'bg-primary text-primary-contrast' },
     { text: 'Edit' },
     {
       text: 'Share',
-      children: [{ text: 'By email', theme: 'custom-theme' }, { text: 'Get link' }],
+      children: [
+        { text: 'By email', className: 'bg-primary text-primary-contrast' },
+        { text: 'Get link' },
+      ],
     },
   ];
 

frontend/themes/docs/styles.css

@@ -6,7 +6,6 @@
 @import './notification-position-example.css';
 @import './board.css';
 @import './grid-cell-focus.css';
-@import './menu-bar-theming.css';
 @import './message-list-theming.css';
 @import './grid-styling.css';
 @import './grid-header-footer-styling.css';

src/main/java/com/vaadin/demo/component/menubar/MenuBarCustomTheme.java → src/main/java/com/vaadin/demo/component/menubar/MenuBarCustomStyling.java

@@ -6,28 +6,34 @@
 import com.vaadin.flow.component.html.Div;
 import com.vaadin.flow.component.menubar.MenuBar;
 import com.vaadin.flow.router.Route;
+import com.vaadin.flow.theme.lumo.LumoUtility;
 
-@Route("menu-bar-custom-theme")
-public class MenuBarCustomTheme extends Div {
+@Route("menu-bar-custom-styling")
+public class MenuBarCustomStyling extends Div {
 
-    public MenuBarCustomTheme() {
+    public MenuBarCustomStyling() {
         MenuBar menuBar = new MenuBar();
 
         // tag::snippet[]
         MenuItem view = menuBar.addItem("View");
-        view.addThemeNames("custom-theme");
+        view.addClassNames(LumoUtility.Background.PRIMARY,
+                LumoUtility.TextColor.PRIMARY_CONTRAST);
+        ;
 
         MenuItem edit = menuBar.addItem("Edit");
 
         MenuItem share = menuBar.addItem("Share");
         SubMenu shareSubMenu = share.getSubMenu();
-        shareSubMenu.addItem("By email").addThemeNames("custom-theme");
+
+        shareSubMenu.addItem("By email").addClassNames(
+                LumoUtility.Background.PRIMARY,
+                LumoUtility.TextColor.PRIMARY_CONTRAST);
         shareSubMenu.addItem("Get Link");
         // end::snippet[]
 
         add(menuBar);
     }
 
-    public static class Exporter extends DemoExporter<MenuBarCustomTheme> { // hidden-source-line
+    public static class Exporter extends DemoExporter<MenuBarCustomStyling> { // hidden-source-line
     } // hidden-source-line
 }