refactor: deprecate hascomponents api and provide alternatives (#7357)

ugur-vaadin · sissbruecker · web-flow · commit c8964666c034 · 2025-05-27T10:52:19.000+02:00
* refactor: deprecate hascomponents api and provide alternatives

* refactor: move addSeparator methods to base classes

* feat: introduce addSeparatorAtIndex to provide an alternative

* refactor: deprecate addComponentAtIndex and provide alternative

* fix: add missing import

* chore: deprecate add component methods

* refactor: revert deprecation of remove methods

* refactor: do not introduce adding items and separators at index

* feat: introduce addcomponent as add alternative

* improve javadoc

* add override for addComponentAsFirst

* improve wording

---------

Co-authored-by: Sascha Ißbrücker &lt;sissbruecker@vaadin.com&gt;
diff --git a/vaadin-context-menu-flow-parent/vaadin-context-menu-flow/src/main/java/com/vaadin/flow/component/contextmenu/ContextMenu.java b/vaadin-context-menu-flow-parent/vaadin-context-menu-flow/src/main/java/com/vaadin/flow/component/contextmenu/ContextMenu.java
@@ -18,7 +18,6 @@
 import com.vaadin.flow.component.ClickEvent;
 import com.vaadin.flow.component.Component;
 import com.vaadin.flow.component.ComponentEventListener;
-import com.vaadin.flow.component.html.Hr;
 import com.vaadin.flow.component.shared.HasOverlayClassName;
 import com.vaadin.flow.function.SerializableRunnable;
 
@@ -83,13 +82,6 @@ public MenuItem addItem(Component component,
         return getMenuManager().addItem(component, clickListener);
     }
 
-    /**
-     * Adds a separator between items.
-     */
-    public void addSeparator() {
-        getMenuManager().add(new Hr());
-    }
-
     @Override
     protected MenuManager<ContextMenu, MenuItem, SubMenu> createMenuManager(
             SerializableRunnable contentReset) {
diff --git a/vaadin-context-menu-flow-parent/vaadin-context-menu-flow/src/main/java/com/vaadin/flow/component/contextmenu/ContextMenuBase.java b/vaadin-context-menu-flow-parent/vaadin-context-menu-flow/src/main/java/com/vaadin/flow/component/contextmenu/ContextMenuBase.java
@@ -15,6 +15,7 @@
  */
 package com.vaadin.flow.component.contextmenu;
 
+import java.util.Collection;
 import java.util.List;
 import java.util.stream.Stream;
 
@@ -199,38 +200,24 @@ public void close() {
     }
 
     /**
-     * Adds a new item component with the given text content to the context menu
-     * overlay.
-     * <p>
-     * This is a convenience method for the use case where you have a list of
-     * highlightable {@link MenuItem}s inside the overlay. If you want to
-     * configure the contents of the overlay without wrapping them inside
-     * {@link MenuItem}s, or if you just want to add some non-highlightable
-     * components between the items, use the {@link #add(Component...)} method.
+     * Creates a new menu item with the given text content and adds it to the
+     * context menu overlay.
      *
      * @param text
      *            the text content for the created menu item
      * @return the created menu item
-     * @see #add(Component...)
      */
     public I addItem(String text) {
         return getMenuManager().addItem(text);
     }
 
     /**
-     * Adds a new item component with the given component to the context menu
-     * overlay.
-     * <p>
-     * This is a convenience method for the use case where you have a list of
-     * highlightable {@link MenuItem}s inside the overlay. If you want to
-     * configure the contents of the overlay without wrapping them inside
-     * {@link MenuItem}s, or if you just want to add some non-highlightable
-     * components between the items, use the {@link #add(Component...)} method.
+     * Creates a new menu item with the given component content and to the
+     * context menu overlay.
      *
      * @param component
      *            the component to add to the created menu item
      * @return the created menu item
-     * @see #add(Component...)
      */
     public I addItem(Component component) {
         return getMenuManager().addItem(component);
@@ -240,7 +227,7 @@ public I addItem(Component component) {
      * Adds the given components into the context menu overlay.
      * <p>
      * For the common use case of having a list of high-lightable items inside
-     * the overlay, you can use the {@link #addItem(String)} convenience methods
+     * the overlay, use {@link #addItem(String)} and its overload methods
      * instead.
      * <p>
      * The added elements in the DOM will not be children of the
@@ -251,10 +238,78 @@ public I addItem(Component component) {
      *            the components to add
      * @see HasMenuItems#addItem(String, ComponentEventListener)
      * @see HasMenuItems#addItem(Component, ComponentEventListener)
+     *
+     * @deprecated Since 24.8, use {@link #addComponent(Component...)} instead
      */
+    @Deprecated(since = "24.8")
     @Override
     public void add(Component... components) {
-        getMenuManager().add(components);
+        addComponent(components);
+    }
+
+    /**
+     * Adds the given components into the context menu overlay.
+     * <p>
+     * For the common use case of having a list of high-lightable items inside
+     * the overlay, use {@link #addItem(String)} and its overload methods
+     * instead.
+     * <p>
+     * The added elements in the DOM will not be children of the
+     * {@code <vaadin-context-menu>} element, but will be inserted into an
+     * overlay that is attached into the {@code <body>}.
+     *
+     * @param components
+     *            the components to add
+     * @see HasMenuItems#addItem(String, ComponentEventListener)
+     * @see HasMenuItems#addItem(Component, ComponentEventListener)
+     */
+    public void addComponent(Component... components) {
+        getMenuManager().addComponent(components);
+    }
+
+    /**
+     * @inheritDoc
+     *
+     * @deprecated Since 24.8, use {@link #addComponent(Collection)} instead
+     */
+    @Deprecated(since = "24.8")
+    @Override
+    public void add(Collection<Component> components) {
+        addComponent(components);
+    }
+
+    /**
+     * Adds the given components into the context menu overlay.
+     * <p>
+     * For the common use case of having a list of high-lightable items inside
+     * the overlay, use {@link #addItem(String)} and its overload methods
+     * instead.
+     * <p>
+     * The added elements in the DOM will not be children of the
+     * {@code <vaadin-context-menu>} element, but will be inserted into an
+     * overlay that is attached into the {@code <body>}.
+     *
+     * @param components
+     *            the components to add
+     * @see HasMenuItems#addItem(String, ComponentEventListener)
+     * @see HasMenuItems#addItem(Component, ComponentEventListener)
+     */
+    public void addComponent(Collection<Component> components) {
+        if (components == null) {
+            return;
+        }
+        getMenuManager().addComponent(components.toArray(Component[]::new));
+    }
+
+    /**
+     * @inheritDoc
+     *
+     * @deprecated Since 24.8, use {@link #addItem(String)} instead
+     */
+    @Deprecated(since = "24.8")
+    @Override
+    public void add(String text) {
+        HasComponents.super.add(text);
     }
 
     @Override
@@ -263,16 +318,21 @@ public void remove(Component... components) {
     }
 
     /**
-     * Removes all of the child components. This also removes all the items
-     * added with {@link #addItem(String)} and its overload methods.
+     * Removes all the child components. This also removes all the items added
+     * with {@link #addItem(String)} and its overload methods.
      */
     @Override
     public void removeAll() {
         getMenuManager().removeAll();
     }
 
     /**
-     * Adds the given component into this context menu at the given index.
+     * Adds the given component into the context menu overlay at the given
+     * index.
+     * <p>
+     * For the common use case of having a list of high-lightable items inside
+     * the overlay, use {@link #addItem(String)} and its overload methods
+     * instead.
      * <p>
      * The added elements in the DOM will not be children of the
      * {@code <vaadin-context-menu>} element, but will be inserted into an
@@ -282,13 +342,39 @@ public void removeAll() {
      *            the index, where the component will be added
      * @param component
      *            the component to add
-     * @see #add(Component...)
      */
     @Override
     public void addComponentAtIndex(int index, Component component) {
         getMenuManager().addComponentAtIndex(index, component);
     }
 
+    /**
+     * Adds the given component as the first child into the context menu
+     * overlay.
+     * <p>
+     * For the common use case of having a list of high-lightable items inside
+     * the overlay, use {@link #addItem(String)} and its overload methods
+     * instead.
+     * <p>
+     * The added elements in the DOM will not be children of the
+     * {@code <vaadin-context-menu>} element, but will be inserted into an
+     * overlay that is attached into the {@code <body>}.
+     *
+     * @param component
+     *            the component to add
+     */
+    @Override
+    public void addComponentAsFirst(Component component) {
+        HasComponents.super.addComponentAsFirst(component);
+    }
+
+    /**
+     * Adds a separator between items.
+     */
+    public void addSeparator() {
+        getMenuManager().addSeparator();
+    }
+
     /**
      * Gets the child components of this component. This includes components
      * added with {@link #add(Component...)} and the {@link MenuItem} components
diff --git a/vaadin-context-menu-flow-parent/vaadin-context-menu-flow/src/main/java/com/vaadin/flow/component/contextmenu/HasMenuItems.java b/vaadin-context-menu-flow-parent/vaadin-context-menu-flow/src/main/java/com/vaadin/flow/component/contextmenu/HasMenuItems.java
@@ -33,15 +33,8 @@
 public interface HasMenuItems extends Serializable {
 
     /**
-     * Adds a new item component with the given text content and click listener
-     * to the context menu overlay.
-     * <p>
-     * This is a convenience method for the use case where you have a list of
-     * highlightable {@link MenuItem}s inside the overlay. If you want to
-     * configure the contents of the overlay without wrapping them inside
-     * {@link MenuItem}s, or if you just want to add some non-highlightable
-     * components between the items, use the
-     * {@link ContextMenu#add(Component...)} method.
+     * Creates a new menu item with the given text content and click listener
+     * and adds it to the context menu overlay.
      *
      * @param text
      *            the text content for the new item
@@ -57,15 +50,8 @@ MenuItem addItem(String text,
             ComponentEventListener<ClickEvent<MenuItem>> clickListener);
 
     /**
-     * Adds a new item component with the given component and click listener to
-     * the context menu overlay.
-     * <p>
-     * This is a convenience method for the use case where you have a list of
-     * highlightable {@link MenuItem}s inside the overlay. If you want to
-     * configure the contents of the overlay without wrapping them inside
-     * {@link MenuItem}s, or if you just want to add some non-highlightable
-     * components between the items, use the
-     * {@link ContextMenu#add(Component...)} method.
+     * Creates a new menu item with the given component content and click
+     * listener and adds it to the context menu overlay.
      *
      * @param component
      *            the component inside the new item
diff --git a/vaadin-context-menu-flow-parent/vaadin-context-menu-flow/src/main/java/com/vaadin/flow/component/contextmenu/MenuManager.java b/vaadin-context-menu-flow-parent/vaadin-context-menu-flow/src/main/java/com/vaadin/flow/component/contextmenu/MenuManager.java
@@ -26,6 +26,7 @@
 import com.vaadin.flow.component.Component;
 import com.vaadin.flow.component.ComponentEventListener;
 import com.vaadin.flow.component.ComponentUtil;
+import com.vaadin.flow.component.html.Hr;
 import com.vaadin.flow.function.SerializableBiFunction;
 import com.vaadin.flow.function.SerializableRunnable;
 
@@ -155,8 +156,25 @@ public I addItem(Component component,
      *            components to add
      * @see #remove(Component...)
      * @see #addComponentAtIndex(int, Component)
+     * @deprecated Since 24.8, use {@link #addComponent(Component...)} instead
      */
+    @Deprecated(since = "24.8")
     public void add(Component... components) {
+        addComponent(components);
+    }
+
+    /**
+     * Adds components to the (sub)menu.
+     * <p>
+     * The components are added into the content as is, they are not wrapped as
+     * menu items.
+     *
+     * @param components
+     *            components to add
+     * @see #remove(Component...)
+     * @see #addComponentAtIndex(int, Component)
+     */
+    public void addComponent(Component... components) {
         if (parentMenuItem != null && parentMenuItem.isCheckable()) {
             throw new IllegalStateException(
                     "A checkable item cannot have a sub menu");
@@ -266,6 +284,13 @@ public List<I> getItems() {
                 .collect(Collectors.toList());
     }
 
+    /**
+     * Adds a separator between items.
+     */
+    public void addSeparator() {
+        addComponent(new Hr());
+    }
+
     private void updateChildren() {
         contentReset.run();
     }
diff --git a/vaadin-context-menu-flow-parent/vaadin-context-menu-flow/src/main/java/com/vaadin/flow/component/contextmenu/SubMenu.java b/vaadin-context-menu-flow-parent/vaadin-context-menu-flow/src/main/java/com/vaadin/flow/component/contextmenu/SubMenu.java
@@ -18,7 +18,6 @@
 import com.vaadin.flow.component.ClickEvent;
 import com.vaadin.flow.component.Component;
 import com.vaadin.flow.component.ComponentEventListener;
-import com.vaadin.flow.component.html.Hr;
 import com.vaadin.flow.function.SerializableRunnable;
 
 /**
@@ -57,11 +56,4 @@ protected MenuManager<ContextMenu, MenuItem, SubMenu> createMenuManager() {
                 contentReset, MenuItem::new, MenuItem.class,
                 getParentMenuItem());
     }
-
-    /**
-     * Adds a separator between items.
-     */
-    public void addSeparator() {
-        add(new Hr());
-    }
 }
diff --git a/vaadin-context-menu-flow-parent/vaadin-context-menu-flow/src/main/java/com/vaadin/flow/component/contextmenu/SubMenuBase.java b/vaadin-context-menu-flow-parent/vaadin-context-menu-flow/src/main/java/com/vaadin/flow/component/contextmenu/SubMenuBase.java
