feat: introduce add and remove widget functionality to dashboard

vaadin-dashboard-flow-parent/vaadin-dashboard-flow-integration-tests/src/main/java/com/vaadin/flow/component/dashboard/tests/DashboardPage.java

@@ -8,12 +8,54 @@
  */
 package com.vaadin.flow.component.dashboard.tests;
 
+import com.vaadin.flow.component.dashboard.Dashboard;
+import com.vaadin.flow.component.dashboard.DashboardWidget;
 import com.vaadin.flow.component.html.Div;
+import com.vaadin.flow.component.html.NativeButton;
 import com.vaadin.flow.router.Route;
 
 /**
  * @author Vaadin Ltd
  */
 @Route("vaadin-dashboard")
 public class DashboardPage extends Div {
+
+    public DashboardPage() {
+        DashboardWidget widget1 = new DashboardWidget();
+        widget1.setTitle("Widget 1");
+        widget1.setId("widget-1");
+
+        DashboardWidget widget2 = new DashboardWidget();
+        widget2.setTitle("Widget 2");
+        widget2.setId("widget-2");
+
+        DashboardWidget widget3 = new DashboardWidget();
+        widget3.setTitle("Widget 3");
+        widget3.setId("widget-3");
+
+        Dashboard dashboard = new Dashboard();
+        dashboard.add(widget1, widget2, widget3);
+
+        NativeButton addWidgetAtIndex1 = new NativeButton(
+                "Add widget at index 1");
+        addWidgetAtIndex1.addClickListener(click -> {
+            DashboardWidget widgetAtIndex1 = new DashboardWidget();
+            widgetAtIndex1.setTitle("Widget at index 1");
+            widgetAtIndex1.setId("widget-at-index-1");
+            dashboard.addWidgetAtIndex(1, widgetAtIndex1);
+        });
+        addWidgetAtIndex1.setId("add-widget-at-index-1");
+
+        NativeButton removeWidgets1And3 = new NativeButton(
+                "Remove widgets 1 and 3");
+        removeWidgets1And3
+                .addClickListener(click -> dashboard.remove(widget1, widget3));
+        removeWidgets1And3.setId("remove-widgets-1-and-3");
+
+        NativeButton removeAllWidgets = new NativeButton("Remove all widgets");
+        removeAllWidgets.addClickListener(click -> dashboard.removeAll());
+        removeAllWidgets.setId("remove-all-widgets");
+
+        add(addWidgetAtIndex1, removeWidgets1And3, removeAllWidgets, dashboard);
+    }
 }

vaadin-dashboard-flow-parent/vaadin-dashboard-flow-integration-tests/src/test/java/com/vaadin/flow/component/dashboard/tests/DashboardIT.java

@@ -8,6 +8,15 @@
  */
 package com.vaadin.flow.component.dashboard.tests;
 
+import java.util.Arrays;
+import java.util.List;
+
+import org.junit.Assert;
+import org.junit.Before;
+import org.junit.Test;
+
+import com.vaadin.flow.component.dashboard.testbench.DashboardElement;
+import com.vaadin.flow.component.dashboard.testbench.DashboardWidgetElement;
 import com.vaadin.flow.testutil.TestPath;
 import com.vaadin.tests.AbstractComponentIT;
 
@@ -16,4 +25,43 @@
  */
 @TestPath("vaadin-dashboard")
 public class DashboardIT extends AbstractComponentIT {
+
+    private DashboardElement dashboardElement;
+
+    @Before
+    public void init() {
+        open();
+        dashboardElement = $(DashboardElement.class).waitForFirst();
+    }
+
+    @Test
+    public void addWidgets_widgetsAreCorrectlyAdded() {
+        assertWidgetsByTitle("Widget 1", "Widget 2", "Widget 3");
+    }
+
+    @Test
+    public void addWidgetsAtIndex1_widgetIsAddedIntoTheCorrectPlace() {
+        $("button").id("add-widget-at-index-1").click();
+        assertWidgetsByTitle("Widget 1", "Widget at index 1", "Widget 2",
+                "Widget 3");
+    }
+
+    @Test
+    public void removeWidgets1And3_widgetsAreCorrectlyRemoved() {
+        $("button").id("remove-widgets-1-and-3").click();
+        assertWidgetsByTitle("Widget 2");
+    }
+
+    @Test
+    public void removeAllWidgets_widgetsAreCorrectlyRemoved() {
+        $("button").id("remove-all-widgets").click();
+        assertWidgetsByTitle();
+    }
+
+    private void assertWidgetsByTitle(String... expectedWidgetTitles) {
+        List<DashboardWidgetElement> widgets = dashboardElement.getWidgets();
+        List<String> widgetTitles = widgets.stream()
+                .map(DashboardWidgetElement::getTitle).toList();
+        Assert.assertEquals(Arrays.asList(expectedWidgetTitles), widgetTitles);
+    }
 }

vaadin-dashboard-flow-parent/vaadin-dashboard-flow/pom.xml

@@ -54,6 +54,11 @@
             <groupId>com.vaadin</groupId>
             <artifactId>flow-html-components</artifactId>
         </dependency>
+        <dependency>
+            <groupId>com.vaadin</groupId>
+            <artifactId>vaadin-renderer-flow</artifactId>
+            <version>${project.version}</version>
+        </dependency>
     </dependencies>
     <build>
         <plugins>

vaadin-dashboard-flow-parent/vaadin-dashboard-flow/src/main/java/com/vaadin/flow/component/dashboard/Dashboard.java

@@ -8,10 +8,29 @@
  */
 package com.vaadin.flow.component.dashboard;
 
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+
+import org.slf4j.LoggerFactory;
+
+import com.vaadin.flow.component.AttachEvent;
 import com.vaadin.flow.component.Component;
 import com.vaadin.flow.component.Tag;
+import com.vaadin.flow.component.UI;
 import com.vaadin.flow.component.dependency.JsModule;
 import com.vaadin.flow.component.dependency.NpmPackage;
+import com.vaadin.flow.dom.Element;
+import com.vaadin.flow.dom.ElementDetachEvent;
+import com.vaadin.flow.dom.ElementDetachListener;
+import com.vaadin.flow.shared.Registration;
+
+import elemental.json.Json;
+import elemental.json.JsonArray;
+import elemental.json.JsonObject;
 
 /**
  * @author Vaadin Ltd
@@ -20,6 +39,207 @@
 @NpmPackage(value = "@vaadin/polymer-legacy-adapter", version = "24.5.0-alpha8")
 @JsModule("@vaadin/polymer-legacy-adapter/style-modules.js")
 @JsModule("@vaadin/dashboard/src/vaadin-dashboard.js")
+@JsModule("./flow-component-renderer.js")
 // @NpmPackage(value = "@vaadin/dashboard", version = "24.6.0-alpha0")
 public class Dashboard extends Component {
+
+    private final List<DashboardWidget> widgets = new ArrayList<>();
+
+    private boolean pendingUpdate = false;
+
+    /**
+     * Creates an empty dashboard.
+     */
+    public Dashboard() {
+        getElement().getNode().addAttachListener(this::attachRenderer);
+    }
+
+    /**
+     * Returns the widgets in the dashboard.
+     *
+     * @return The widgets in the dashboard
+     */
+    public List<DashboardWidget> getWidgets() {
+        return Collections.unmodifiableList(widgets);
+    }
+
+    /**
+     * Adds the given widgets to the dashboard.
+     *
+     * @param widgets
+     *            the widgets to add, not {@code null}
+     */
+    public void add(DashboardWidget... widgets) {
+        Objects.requireNonNull(widgets, "Widgets to add cannot be null.");
+        List<DashboardWidget> toAdd = new ArrayList<>(widgets.length);
+        for (DashboardWidget widget : widgets) {
+            Objects.requireNonNull(widget, "Widget to add cannot be null.");
+            toAdd.add(widget);
+        }
+        toAdd.forEach(this::doAddWidget);
+        updateClient();
+    }
+
+    /**
+     * Adds the given widget as child of this dashboard at the specific index.
+     * <p>
+     * In case the specified widget has already been added to another parent, it
+     * will be removed from there and added to this one.
+     *
+     * @param index
+     *            the index, where the widget will be added. The index must be
+     *            non-negative and may not exceed the children count
+     * @param widget
+     *            the widget to add, not {@code null}
+     */
+    public void addWidgetAtIndex(int index, DashboardWidget widget) {
+        Objects.requireNonNull(widget, "Widget to add cannot be null.");
+        if (index < 0) {
+            throw new IllegalArgumentException(
+                    "Cannot add a widget with a negative index.");
+        }
+        // The case when the index is bigger than the children count is handled
+        // inside the method below
+        doAddWidget(index, widget);
+        updateClient();
+    }
+
+    /**
+     * Removes the given widgets from this dashboard.
+     *
+     * @param widgets
+     *            the widgets to remove, not {@code null}
+     * @throws IllegalArgumentException
+     *             if there is a widget whose non {@code null} parent is not
+     *             this dashboard
+     */
+    public void remove(DashboardWidget... widgets) {
+        Objects.requireNonNull(widgets, "Widgets to remove cannot be null.");
+        List<DashboardWidget> toRemove = new ArrayList<>(widgets.length);
+        for (DashboardWidget widget : widgets) {
+            Objects.requireNonNull(widget, "Widget to remove cannot be null.");
+            Element parent = widget.getElement().getParent();
+            if (parent == null) {
+                LoggerFactory.getLogger(getClass()).debug(
+                        "Removal of a widget with no parent does nothing.");
+                continue;
+            }
+            if (getElement().equals(parent)) {
+                toRemove.add(widget);
+            } else {
+                throw new IllegalArgumentException("The given widget (" + widget
+                        + ") is not a child of this dashboard");
+            }
+        }
+        toRemove.forEach(this::doRemoveWidget);
+        updateClient();
+    }
+
+    /**
+     * Removes all widgets from this dashboard.
+     */
+    public void removeAll() {
+        doRemoveAllWidgets();
+        updateClient();
+    }
+
+    private final Map<Element, Registration> childDetachListenerMap = new HashMap<>();
+
+    // Must not use lambda here as that would break serialization. See
+    // https://github.com/vaadin/flow-components/issues/5597
+    private final ElementDetachListener childDetachListener = new ElementDetachListener() {
+        @Override
+        public void onDetach(ElementDetachEvent e) {
+            var detachedElement = e.getSource();
+            getWidgets().stream()
+                    .filter(widget -> Objects.equals(detachedElement,
+                            widget.getElement()))
+                    .findAny().ifPresent(detachedWidget -> {
+                        // The child was removed from the dashboard
+
+                        // Remove the registration for the child detach listener
+                        childDetachListenerMap.get(detachedWidget.getElement())
+                                .remove();
+                        childDetachListenerMap
+                                .remove(detachedWidget.getElement());
+
+                        doRemoveWidget(detachedWidget);
+                        updateClient();
+                    });
+        }
+    };
+
+    @Override
+    protected void onAttach(AttachEvent attachEvent) {
+        super.onAttach(attachEvent);
+        updateClient();
+    }
+
+    private void updateClient() {
+        if (pendingUpdate) {
+            return;
+        }
+        pendingUpdate = true;
+        getElement().getNode()
+                .runWhenAttached(ui -> ui.beforeClientResponse(this, ctx -> {
+                    doUpdateClient();
+                    pendingUpdate = false;
+                }));
+    }
+
+    private void doUpdateClient() {
+        getElement().getChildren().forEach(child -> {
+            if (!childDetachListenerMap.containsKey(child)) {
+                childDetachListenerMap.put(child,
+                        child.addDetachListener(childDetachListener));
+            }
+        });
+        List<Integer> widgetNodeIds = getWidgets().stream()
+                .map(this::getWidgetNodeId).toList();
+        getElement().setPropertyList("virtualChildNodeIds", widgetNodeIds);
+        getElement().setPropertyJson("items", createItemsJsonArray());
+    }
+
+    private void attachRenderer() {
+        getElement().executeJs(
+                "Vaadin.FlowComponentHost.patchVirtualContainer(this);");
+        String appId = UI.getCurrent().getInternals().getAppId();
+        getElement().executeJs(
+                "this.renderer = (root, _, model) => Vaadin.FlowComponentHost.setChildNodes($0, [model.item.nodeid], root);",
+                appId);
+    }
+
+    private JsonArray createItemsJsonArray() {
+        JsonArray jsonItems = Json.createArray();
+        for (DashboardWidget widget : widgets) {
+            JsonObject jsonItem = Json.createObject();
+            jsonItem.put("nodeid", getWidgetNodeId(widget));
+            jsonItems.set(jsonItems.length(), jsonItem);
+        }
+        return jsonItems;
+    }
+
+    private int getWidgetNodeId(DashboardWidget widget) {
+        return widget.getElement().getNode().getId();
+    }
+
+    private void doRemoveAllWidgets() {
+        widgets.clear();
+        getElement().removeAllChildren();
+    }
+
+    private void doRemoveWidget(DashboardWidget widget) {
+        widgets.remove(widget);
+        getElement().removeChild(widget.getElement());
+    }
+
+    private void doAddWidget(int index, DashboardWidget widget) {
+        widgets.add(index, widget);
+        getElement().insertChild(index, widget.getElement());
+    }
+
+    private void doAddWidget(DashboardWidget widget) {
+        widgets.add(widget);
+        getElement().appendChild(widget.getElement());
+    }
 }