feat: add listener for share actions

README.md

@@ -14,6 +14,7 @@ This component is a wrapper of [Sharee](https://github.com/parsagholipour/sharee
 - Default social media drivers to share links easily: Copy, Twitter, Facebook, Linkedin, Whatsapp, Telegram.
 - Modes to display the Easy Share menu: Fixed, Normal, Hover, Text, Dropdown.
 - By defaut, locale and keys are in English but custom locales and keys can be defined.
+- Listen to share actions to track which driver was clicked.
 
 ## Supported versions
 
@@ -114,6 +115,20 @@ NormalShareEasy.create().withNoTitle(true).forComponent(div);
 add(div);
 ```
 
+## Listening to share actions
+
+Register a listener to be notified when one of the share drivers is clicked. The event exposes the
+clicked driver (both as the raw name and, for default drivers, as a `Driver` enum value) and the
+share link:
+
+```java
+Div div = new Div();
+NormalShareEasy.create()
+    .withShareListener(event -> Notification.show("Shared via " + event.getDriverName()))
+    .forComponent(div);
+add(div);
+```
+
 ## Special configuration when using Spring
 
 By default, Vaadin Flow only includes ```com/vaadin/flow/component``` to be always scanned for UI components and views. For this reason, the addon might need to be whitelisted in order to display correctly. 

pom.xml

@@ -4,7 +4,7 @@
 
 	<groupId>org.vaadin.addons.flowingcode</groupId>
 	<artifactId>share-easy-addon</artifactId>
-	<version>2.1.1-SNAPSHOT</version>
+	<version>2.2.0-SNAPSHOT</version>
 	<name>Share Easy Add-on</name>
 	<description>Share Eady Add-on for Vaadin Flow</description>
 
@@ -117,6 +117,11 @@
 			<artifactId>vaadin-core</artifactId>
 			<optional>true</optional>
 		</dependency>
+		<dependency>
+            <groupId>com.flowingcode.vaadin</groupId>
+            <artifactId>json-migration-helper</artifactId>
+            <version>0.9.3</version>
+        </dependency>
 		<dependency>
 			<groupId>org.slf4j</groupId>
 			<artifactId>slf4j-simple</artifactId>
@@ -148,14 +153,20 @@
 		<dependency>
 			<groupId>io.github.bonigarcia</groupId>
 			<artifactId>webdrivermanager</artifactId>
-            <version>5.1.1</version>
+            <version>5.9.2</version>
 			<scope>test</scope>
 		</dependency>
 		<dependency>
 			<groupId>com.vaadin.external.gwt</groupId>
 			<artifactId>gwt-elemental</artifactId>
 			<version>2.8.2.vaadin2</version>
 			<scope>compile</scope>
+		</dependency>		 
+		<dependency>
+			<groupId>org.projectlombok</groupId>
+			<artifactId>lombok</artifactId>
+			<version>1.18.34</version>
+			<scope>provided</scope>
 		</dependency>
 	</dependencies>
 

src/main/java/com/flowingcode/vaadin/addons/shareeasy/BaseShareEasy.java

@@ -21,16 +21,22 @@
 
 import java.util.HashMap;
 import java.util.Map;
+
 import com.flowingcode.vaadin.addons.shareeasy.enums.Driver;
 import com.flowingcode.vaadin.addons.shareeasy.enums.Locale;
 import com.flowingcode.vaadin.addons.shareeasy.util.CustomDriverOptions;
 import com.flowingcode.vaadin.addons.shareeasy.util.LanguageKeys;
 import com.flowingcode.vaadin.addons.shareeasy.util.Options;
+import com.flowingcode.vaadin.jsonmigration.JsonMigration;
 import com.vaadin.flow.component.Component;
 import com.vaadin.flow.component.dependency.CssImport;
 import com.vaadin.flow.component.dependency.JsModule;
 import com.vaadin.flow.component.dependency.NpmPackage;
+import com.vaadin.flow.shared.Registration;
+
 import elemental.json.JsonObject;
+import elemental.json.JsonString;
+import lombok.experimental.ExtensionMethod;
 
 /**
  * BaseSharee represents the base class for creating Sharee instances.
@@ -42,16 +48,21 @@
 @NpmPackage(value = "sharee", version = "1.1.24")
 @JsModule("./src/fc-sharee-connector.js")
 @CssImport("./styles/fc-share-easy/style.css")
+@ExtensionMethod(value = JsonMigration.class, suppressBaseMethods = true)
 class BaseShareEasy<T extends BaseShareEasy<T>> {
 
   private Component component;
 
   private Options options = new Options();
 
   Map<String, CustomDriverOptions> customDrivers = new HashMap<>();
-  
+
   protected boolean withDefaultDriversListFirst = true;
 
+  private ShareEasyClickListener shareListener;
+
+  private Registration shareListenerRegistration;
+
   /**
    * Sets the share link for the shared content.
    *
@@ -121,6 +132,17 @@ public T withDrivers(ShareEasyDriver... drivers) {
     return (T) this;
   }
 
+  /**
+   * Sets the listener that is notified when one of the share drivers is clicked.
+   *
+   * @param shareListener the listener to notify on driver clicks
+   * @return The current instance of the BaseSharee class
+   */
+  public T withShareListener(ShareEasyClickListener shareListener) {
+    this.shareListener = shareListener;
+    return (T) this;
+  }
+
   /**
    * Initializes the Sharee component with the specified Vaadin component.
    *
@@ -141,6 +163,7 @@ protected JsonObject getJsonObjectOptions() {
   }
 
   private void createSharee() {
+    registerShareListener();
     String shareeOptions = getJsonObjectOptions().toJson();
     if(customDrivers.isEmpty()) {
       this.create(shareeOptions);
@@ -162,6 +185,26 @@ private void create(String shareeOptions) {
     component.getElement().executeJs("fcShareeConnector.create(this, $0)", shareeOptions);
   }
 
+  private void registerShareListener() {
+    if (shareListenerRegistration != null) {
+      shareListenerRegistration.remove();
+      shareListenerRegistration = null;
+    }
+    if (shareListener == null) {
+      return;
+    }
+    shareListenerRegistration = component.getElement().addEventListener("driver-clicked", event -> {
+      JsonObject detail = event.getEventData();
+      String driverName = getStringOrNull(detail, "event.detail.name");
+      String link = getStringOrNull(detail, "event.detail.link");
+      shareListener.onShare(new ShareEasyClickEvent(component, driverName, link));
+    }).addEventData("event.detail.name").addEventData("event.detail.link");
+  }
+
+  private static String getStringOrNull(JsonObject data, String key) {
+    return data.hasKey(key) && data.get(key) instanceof JsonString ? data.getString(key) : null;
+  }
+
   /**
    * Sets custom language keys for the default locale.
    * 

src/main/java/com/flowingcode/vaadin/addons/shareeasy/ShareEasyClickEvent.java

@@ -0,0 +1,93 @@
+/*-
+ * #%L
+ * Share Easy Add-on
+ * %%
+ * Copyright (C) 2023 - 2026 Flowing Code
+ * %%
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * #L%
+ */
+package com.flowingcode.vaadin.addons.shareeasy;
+
+import java.io.Serializable;
+import java.util.Objects;
+import java.util.Optional;
+import com.flowingcode.vaadin.addons.shareeasy.enums.Driver;
+import com.vaadin.flow.component.Component;
+
+/**
+ * Event fired when one of the share drivers is clicked.
+ *
+ * @author Paola De Bartolo / Flowing Code
+ */
+@SuppressWarnings("serial")
+public class ShareEasyClickEvent implements Serializable {
+
+  private final Component source;
+
+  private final String driverName;
+
+  private final String link;
+
+  /**
+   * Creates a new share click event.
+   *
+   * @param source the component the Share Easy instance is attached to
+   * @param driverName the name of the clicked driver, e.g. "telegram"
+   * @param link the share link associated with the driver (the copied URL for the copy driver); may
+   *        be {@code null} for custom drivers without a link
+   */
+  public ShareEasyClickEvent(Component source, String driverName, String link) {
+    this.source = Objects.requireNonNull(source, "source must not be null");
+    this.driverName = Objects.requireNonNull(driverName, "driverName must not be null");
+    this.link = link;
+  }
+
+  /**
+   * Gets the component the Share Easy instance is attached to.
+   *
+   * @return the source component
+   */
+  public Component getSource() {
+    return source;
+  }
+
+  /**
+   * Gets the name of the clicked driver.
+   *
+   * @return the driver name, e.g. "telegram"
+   */
+  public String getDriverName() {
+    return driverName;
+  }
+
+  /**
+   * Gets the clicked driver as a {@link Driver default driver}, if it corresponds to one.
+   *
+   * @return the matching default {@link Driver}, or an empty {@link Optional} if the clicked driver
+   *         is a custom driver
+   */
+  public Optional<Driver> getDriver() {
+    return Driver.fromName(driverName);
+  }
+
+  /**
+   * Gets the share link associated with the clicked driver. For the copy driver this is the URL that
+   * was copied to the clipboard.
+   *
+   * @return the share link, or {@code null} for custom drivers without a link
+   */
+  public String getLink() {
+    return link;
+  }
+}

src/main/java/com/flowingcode/vaadin/addons/shareeasy/ShareEasyClickListener.java

@@ -0,0 +1,43 @@
+/*-
+ * #%L
+ * Share Easy Add-on
+ * %%
+ * Copyright (C) 2023 - 2026 Flowing Code
+ * %%
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * #L%
+ */
+package com.flowingcode.vaadin.addons.shareeasy;
+
+import com.vaadin.flow.function.SerializableConsumer;
+
+/**
+ * Listener notified when one of the share drivers is clicked.
+ *
+ * @author Paola De Bartolo / Flowing Code
+ */
+@FunctionalInterface
+public interface ShareEasyClickListener extends SerializableConsumer<ShareEasyClickEvent> {
+
+  /**
+   * Invoked when a share driver is clicked.
+   *
+   * @param event the share click event
+   */
+  void onShare(ShareEasyClickEvent event);
+
+  @Override
+  default void accept(ShareEasyClickEvent event) {
+    onShare(event);
+  }
+}

src/main/java/com/flowingcode/vaadin/addons/shareeasy/enums/Driver.java

@@ -19,6 +19,7 @@
  */
 package com.flowingcode.vaadin.addons.shareeasy.enums;
 
+import java.util.Optional;
 import com.flowingcode.vaadin.addons.shareeasy.ShareEasyDriver;
 
 /**
@@ -40,4 +41,21 @@ private Driver(String name) {
   public String getName() {
     return name;
   }
+
+  /**
+   * Resolves a default driver from its name (the name carried by the share event), if it matches one
+   * of the default drivers.
+   *
+   * @param name the driver name, e.g. "telegram"
+   * @return the matching {@link Driver}, or an empty {@link Optional} if the name does not correspond
+   *         to a default driver (for instance, a custom driver)
+   */
+  public static Optional<Driver> fromName(String name) {
+    for (Driver driver : values()) {
+      if (driver.name.equals(name)) {
+        return Optional.of(driver);
+      }
+    }
+    return Optional.empty();
+  }
 }