feat: cluster click event (#8081)

* feat: add cluster support for Map

* remove circle configuration

* use image style by default

* merge ClusterLayer into FeatureLayer

* filter point based features

* update ITs

* cleanup

* silence sonar

* fix units test

* cleanup

* fix default tests

* add rendering ITs

* fix layers IT

* feat: cluster click event

* cleanup FeatureLayer.java

* improve JavaDoc

Author: sissbruecker

vaadin-map-flow-parent/vaadin-map-flow-integration-tests/src/main/java/com/vaadin/flow/component/map/ClusterPage.java

@@ -8,6 +8,8 @@
  */
 package com.vaadin.flow.component.map;
 
+import java.util.stream.Collectors;
+
 import com.vaadin.flow.component.html.Div;
 import com.vaadin.flow.component.html.NativeButton;
 import com.vaadin.flow.component.map.configuration.Coordinate;
@@ -39,7 +41,23 @@ public ClusterPage() {
                 "Customize cluster style", e -> customizeClusterStyle(map));
         customizeStyleButton.setId("customize-style");
 
-        add(map, toggleClusteringButton, customizeStyleButton);
+        Div eventLog = new Div();
+        eventLog.setId("event-log");
+        eventLog.getElement().getStyle().set("white-space", "pre");
+
+        map.addClusterClickListener(event -> {
+            String features = event.getFeatures().stream()
+                    .map(info -> info.getFeature().getId()).sorted()
+                    .collect(Collectors.joining(", "));
+            eventLog.add(new Div("cluster-click: " + features));
+        });
+
+        map.addFeatureClickListener(event -> {
+            eventLog.add(
+                    new Div("feature-click: " + event.getFeature().getId()));
+        });
+
+        add(map, toggleClusteringButton, customizeStyleButton, eventLog);
     }
 
     private void configureClustering(Map map) {

vaadin-map-flow-parent/vaadin-map-flow-integration-tests/src/test/java/com/vaadin/flow/components/map/ClusterIT.java

@@ -15,16 +15,19 @@
 import com.vaadin.flow.component.map.Assets;
 import com.vaadin.flow.component.map.testbench.MapElement;
 import com.vaadin.flow.testutil.TestPath;
+import com.vaadin.testbench.TestBenchElement;
 import com.vaadin.tests.AbstractComponentIT;
 
 @TestPath("vaadin-map/cluster")
 public class ClusterIT extends AbstractComponentIT {
     private MapElement map;
+    private TestBenchElement eventLog;
 
     @Before
     public void init() {
         open();
         map = $(MapElement.class).waitForFirst();
+        eventLog = $("div").id("event-log");
     }
 
     @Test
@@ -170,4 +173,34 @@ public void renderCluster_withCustomClusterStyle_usesCustomStyle() {
         Assert.assertEquals(0, text.getOffsetX());
         Assert.assertEquals(0, text.getOffsetY());
     }
+
+    @Test
+    public void clickCluster_triggersClusterClickEvent() {
+        map.clickAtCoordinates(0, 0);
+
+        // Click events are delayed by around 250ms, wait for event
+        waitSeconds(1);
+
+        Assert.assertEquals("cluster-click: m1, m2, m3", eventLog.getText());
+    }
+
+    @Test
+    public void clickClusterWithSingleFeature_triggersFeatureClickEvent() {
+        map.getMapReference().getView().setZoom(6);
+
+        map.clickAtCoordinates(0, 0);
+
+        // Click events are delayed by around 250ms, wait for event
+        waitSeconds(1);
+
+        Assert.assertEquals("feature-click: m1", eventLog.getText());
+    }
+
+    private void waitSeconds(int seconds) {
+        try {
+            Thread.sleep(seconds * 1000L);
+        } catch (InterruptedException e) {
+            throw new RuntimeException(e);
+        }
+    }
 }

vaadin-map-flow-parent/vaadin-map-flow/src/main/java/com/vaadin/flow/component/map/MapBase.java

@@ -26,6 +26,7 @@
 import com.vaadin.flow.component.map.configuration.View;
 import com.vaadin.flow.component.map.configuration.layer.VectorLayer;
 import com.vaadin.flow.component.map.events.MapClickEvent;
+import com.vaadin.flow.component.map.events.MapClusterClickEvent;
 import com.vaadin.flow.component.map.events.MapFeatureClickEvent;
 import com.vaadin.flow.component.map.events.MapFeatureDropEvent;
 import com.vaadin.flow.component.map.events.MapViewMoveEndEvent;
@@ -233,6 +234,11 @@ public Registration addClickListener(
      * invoked for a click on any feature in the specified layer. For clicks on
      * overlapping features, the listener will be invoked only for the top-level
      * feature at that location.
+     * <p>
+     * When clustering is enabled, the listener will only be invoked for clicks
+     * on individual features. Use
+     * {@link #addClusterClickListener(ComponentEventListener)} to listen for
+     * clicks on clusters.
      *
      * @param listener
      *            the listener to trigger
@@ -256,6 +262,11 @@ public Registration addFeatureClickListener(VectorLayer layer,
      * {@link #addFeatureClickListener(VectorLayer, ComponentEventListener)}.
      * For clicks on overlapping features, the listener will be invoked only for
      * the top-level feature at that location.
+     * <p>
+     * When clustering is enabled, the listener will only be invoked for clicks
+     * on individual features. Use
+     * {@link #addClusterClickListener(ComponentEventListener)} to listen for
+     * clicks on clusters.
      *
      * @param listener
      *            the listener to trigger
@@ -267,6 +278,21 @@ public Registration addFeatureClickListener(
         return addListener(MapFeatureClickEvent.class, listener);
     }
 
+    /**
+     * Adds a click listener for clusters of features. The listener will be
+     * invoked for a click on any cluster, in any feature layer. Use
+     * {@link #addFeatureClickListener(ComponentEventListener)} to listen for
+     * clicks on individual features.
+     *
+     * @param listener
+     *            the listener to trigger
+     * @return registration for the listener
+     */
+    public Registration addClusterClickListener(
+            ComponentEventListener<MapClusterClickEvent> listener) {
+        return addListener(MapClusterClickEvent.class, listener);
+    }
+
     /**
      * Adds an event listener for when a feature is dropped after a drag
      * operation. Features can be made draggable by setting

vaadin-map-flow-parent/vaadin-map-flow/src/main/java/com/vaadin/flow/component/map/events/MapClusterClickEvent.java

@@ -0,0 +1,81 @@
+/**
+ * Copyright 2000-2025 Vaadin Ltd.
+ *
+ * This program is available under Vaadin Commercial License and Service Terms.
+ *
+ * See {@literal <https://vaadin.com/commercial-license-and-service-terms>} for the full
+ * license.
+ */
+package com.vaadin.flow.component.map.events;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+import com.vaadin.flow.component.ComponentEvent;
+import com.vaadin.flow.component.DomEvent;
+import com.vaadin.flow.component.EventData;
+import com.vaadin.flow.component.map.Map;
+import com.vaadin.flow.component.map.MapBase;
+
+import tools.jackson.databind.node.ArrayNode;
+
+/**
+ * Provides data for click events on a cluster of features
+ */
+@DomEvent("map-cluster-click")
+public class MapClusterClickEvent extends ComponentEvent<MapBase> {
+
+    private final List<FeatureEventDetails> features;
+    private final MouseEventDetails details;
+
+    public MapClusterClickEvent(Map source, boolean fromClient,
+            @EventData("event.detail.features.map(feature => feature.id)") ArrayNode featureIds,
+            @EventData("event.detail.layer.id") String layerId,
+            @EventData("event.detail.originalEvent.pageX") int pageX,
+            @EventData("event.detail.originalEvent.pageY") int pageY,
+            @EventData("event.detail.originalEvent.altKey") boolean altKey,
+            @EventData("event.detail.originalEvent.ctrlKey") boolean ctrlKey,
+            @EventData("event.detail.originalEvent.metaKey") boolean metaKey,
+            @EventData("event.detail.originalEvent.shiftKey") boolean shiftKey,
+            @EventData("event.detail.originalEvent.button") int button) {
+        super(source, fromClient);
+
+        List<FeatureEventDetails> features = new ArrayList<>();
+        for (int i = 0; i < featureIds.size(); i++) {
+            String featureId = featureIds.get(i).asString();
+            FeatureEventDetails featureEventDetails = MapEventUtil
+                    .getFeatureEventDetails(source.getRawConfiguration(),
+                            layerId, featureId);
+            features.add(featureEventDetails);
+        }
+        this.features = Collections.unmodifiableList(features);
+
+        details = new MouseEventDetails();
+        details.setAbsoluteX(pageX);
+        details.setAbsoluteY(pageY);
+        details.setButton(MouseEventDetails.MouseButton.of(button));
+        details.setAltKey(altKey);
+        details.setCtrlKey(ctrlKey);
+        details.setMetaKey(metaKey);
+        details.setShiftKey(shiftKey);
+    }
+
+    /**
+     * List of map features in the cluster.
+     *
+     * @return the list of features in the cluster
+     */
+    public List<FeatureEventDetails> getFeatures() {
+        return features;
+    }
+
+    /**
+     * Gets the click's mouse event details.
+     *
+     * @return mouse event details
+     */
+    public MouseEventDetails getMouseDetails() {
+        return details;
+    }
+}

vaadin-map-flow-parent/vaadin-map-flow/src/main/resources/META-INF/resources/frontend/vaadin-map/mapConnector.js

@@ -12,7 +12,7 @@ import { setUserProjection as openLayersSetUserProjection } from 'ol/proj';
 import { register as openLayersRegisterProjections } from 'ol/proj/proj4';
 import proj4 from 'proj4';
 import { synchronize } from './synchronization/index.js';
-import { createLookup, getLayerForFeature } from './util';
+import { createLookup, getFeatureInfo } from './util';
 
 // By default, use EPSG:4326 projection for all coordinates passed to, and return from the public API.
 // Internally coordinates will be converted to the projection used by the map's view.
@@ -99,40 +99,50 @@ function init(mapElement) {
     // back-most feature as the last result
     const pixelCoordinate = event.pixel;
     const featuresAtPixel = mapElement.configuration.getFeaturesAtPixel(pixelCoordinate);
-    // Create tuples of features and the layer that they are in
-    const featuresAndLayers = featuresAtPixel.map((feature) => {
-      const layer = getLayerForFeature(mapElement.configuration.getLayers().getArray(), feature);
-      return {
-        feature,
-        layer
-      };
-    });
+    const featureInfos = featuresAtPixel.map((feature) => getFeatureInfo(mapElement.configuration, feature));
 
     // Map click event
+    const nonClusterFeatures = featureInfos.filter((info) => info && !info.isCluster);
     const mapClickEvent = new CustomEvent('map-click', {
       detail: {
         coordinate,
-        features: featuresAndLayers,
+        features: nonClusterFeatures,
         originalEvent: event.originalEvent
       }
     });
 
     mapElement.dispatchEvent(mapClickEvent);
 
     // Feature click event
-    if (featuresAndLayers.length > 0) {
+    if (nonClusterFeatures.length > 0) {
       // Send a feature click event for the top-level feature
-      const featureAndLayer = featuresAndLayers[0];
+      const featureInfo = nonClusterFeatures[0];
       const featureClickEvent = new CustomEvent('map-feature-click', {
         detail: {
-          feature: featureAndLayer.feature,
-          layer: featureAndLayer.layer,
+          feature: featureInfo.feature,
+          layer: featureInfo.layer,
           originalEvent: event.originalEvent
         }
       });
 
       mapElement.dispatchEvent(featureClickEvent);
     }
+
+    // Cluster click event
+    const clusterInfos = featureInfos.filter((info) => info && info.isCluster);
+    if (clusterInfos.length > 0) {
+      // Send a cluster click event for the top-level cluster
+      const clusterInfo = clusterInfos[0];
+      const clusterClickEvent = new CustomEvent('map-cluster-click', {
+        detail: {
+          features: clusterInfo.feature.get('features'),
+          layer: clusterInfo.layer,
+          originalEvent: event.originalEvent
+        }
+      });
+
+      mapElement.dispatchEvent(clusterClickEvent);
+    }
   });
 
   // Feature drag&drop
@@ -144,12 +154,12 @@ function init(mapElement) {
   translate.on('translateend', (event) => {
     const feature = event.features.item(0);
     if (!feature) return;
-    const layer = getLayerForFeature(mapElement.configuration.getLayers().getArray(), feature);
 
+    const featureInfo = getFeatureInfo(mapElement.configuration, feature);
     const featureDropEvent = new CustomEvent('map-feature-drop', {
       detail: {
         feature,
-        layer,
+        layer: featureInfo.layer,
         coordinate: event.coordinate,
         startCoordinate: event.startCoordinate
       }

vaadin-map-flow-parent/vaadin-map-flow/src/main/resources/META-INF/resources/frontend/vaadin-map/util.js

@@ -75,16 +75,36 @@ export function createLookup() {
 }
 
 /**
- * Searches an OpenLayers map instance for the layer whose source contains a specific feature
- * @param layers the array of layers configured in the map
- * @param feature the feature that should be contained in the layers source
- * @returns {*} the layer that contains the feature, or undefined
+ * Returns information about a feature within an OpenLayers map instance.
+ * Includes whether the feature is a cluster or a single feature, and
+ * which layer and source it belongs to.
+ * @param map
+ * @param feature
+ * @returns {{feature: *, layer: *, source: *, isCluster: boolean}}
  */
-export function getLayerForFeature(layers, feature) {
-  return layers.find((layer) => {
-    const source = layer.getSource && layer.getSource();
-    const isVectorSource = source && source instanceof VectorSource;
+export function getFeatureInfo(map, feature) {
+  const layer = map
+    .getLayers()
+    .getArray()
+    .find((layer) => {
+      const source = layer.getSource && layer.getSource();
+      const isVectorSource = source && source instanceof VectorSource;
+      return isVectorSource && source.getFeatures().includes(feature);
+    });
+  const source = layer && layer.getSource();
+
+  // Unwrap single feature from cluster
+  const clusterFeatures = feature.get('features');
+  if (Array.isArray(clusterFeatures) && clusterFeatures.length === 1) {
+    feature = clusterFeatures[0];
+  }
+
+  const isCluster = Array.isArray(clusterFeatures) && clusterFeatures.length > 1;
 
-    return isVectorSource && source.getFeatures().includes(feature);
-  });
+  return {
+    feature,
+    layer,
+    source,
+    isCluster
+  };
 }