Initial implementation of Image Crop add-on

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -1,5 +1,5 @@
 name: Bug Report
-description: Please report issues related to TEMPLATE_ADDON here.
+description: Please report issues related to Image Crop add-on here.
 body:
   - type: textarea
     id: problem-description

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -1,5 +1,5 @@
 name: Feature Request
-description: Please add feature suggestions related to TEMPLATE_ADDON here.
+description: Please add feature suggestions related to Image Crop add-on here.
 body:
   - type: textarea
     id: feature-proposal

.gitignore

@@ -13,8 +13,9 @@ drivers
 tsconfig.json
 .idea
 types.d.ts
-/frontend/generated
-/frontend/index.html
 vite.generated.ts
 vite.config.ts
-/src/main/dev-bundle
+/src/main/dev-bundle
+/src/main/bundles
+/src/main/frontend/generated
+/src/main/frontend/index.html

README.md

@@ -1,23 +1,37 @@
-[![Published on Vaadin Directory](https://img.shields.io/badge/Vaadin%20Directory-published-00b4f0.svg)](https://vaadin.com/directory/component/template-addon)
-[![Stars on vaadin.com/directory](https://img.shields.io/vaadin-directory/star/template-addon.svg)](https://vaadin.com/directory/component/template-addon)
-[![Build Status](https://jenkins.flowingcode.com/job/template-addon/badge/icon)](https://jenkins.flowingcode.com/job/template-addon)
-[![Maven Central](https://img.shields.io/maven-central/v/com.flowingcode.vaadin.addons/template-addon)](https://mvnrepository.com/artifact/com.flowingcode.vaadin.addons/template-addon)
+[![Published on Vaadin Directory](https://img.shields.io/badge/Vaadin%20Directory-published-00b4f0.svg)](https://vaadin.com/directory/component/image-crop-add-on)
+[![Stars on vaadin.com/directory](https://img.shields.io/vaadin-directory/star/image-crop-add-on.svg)](https://vaadin.com/directory/component/image-crop-add-on)
+[![Build Status](https://jenkins.flowingcode.com/job/ImageCrop-addon/badge/icon)](https://jenkins.flowingcode.com/job/ImageCrop-addon)
+[![Maven Central](https://img.shields.io/maven-central/v/com.flowingcode.vaadin.addons/image-crop-addon)](https://mvnrepository.com/artifact/com.flowingcode.vaadin.addons/image-crop-addon)
 
-# Template Add-on
+# Image Crop Add-on
 
-This is a template project for building new Vaadin 24 add-ons
+Component for cropping images. Wrapper for React component [react-image-crop](https://www.npmjs.com/package/react-image-crop).
 
 ## Features
 
-* List the features of your add-on in here
+The component allows to crop images and configure the following properties for a customized crop:
+* crop dimensions (unit, x and y coordinates, width, and height) 
+* aspect ratio (for example, 1 for a square or 16/9 for landscape)
+* circular crop (selection are has circular shape)
+* keep selection (selection can't be disabled if the user clicks outside the selection area)
+* disabled (cannot resize or draw a new crop)
+* locked (cannot create or resize a crop, but can still drag the existing crop around)
+* min width (minimum crop width)
+* min height (minimum crop height)
+* max width (maximum crop width)
+* max height (maximum crop height)
+* rule of thirds (to show rule of thirds lines in the cropped area)
+
+The cropped image result can be obtain as a URI using `getCroppedImageDataUri` method
+or as a Base64 encoded byte array by using `getCroppedImageBase64` method.
 
 ## Online demo
 
-[Online demo here](http://addonsv24.flowingcode.com/template)
+[Online demo here](http://addonsv24.flowingcode.com/image-crop)
 
 ## Download release
 
-[Available in Vaadin Directory](https://vaadin.com/directory/component/template-addon)
+[Available in Vaadin Directory](https://vaadin.com/directory/component/image-crop-add-on)
 
 ### Maven install
 
@@ -26,7 +40,7 @@ Add the following dependencies in your pom.xml file:
 ```xml
 <dependency>
    <groupId>com.flowingcode.vaadin.addons</groupId>
-   <artifactId>template-addon</artifactId>
+   <artifactId>image-crop-addon</artifactId>
    <version>X.Y.Z</version>
 </dependency>
 ```
@@ -50,7 +64,7 @@ To see the demo, navigate to http://localhost:8080/
 
 ## Release notes
 
-See [here](https://github.com/FlowingCode/TemplateAddon/releases)
+See [here](https://github.com/FlowingCode/ImageCrop/releases)
 
 ## Issue tracking
 
@@ -75,20 +89,32 @@ Then, follow these steps for creating a contribution:
 
 This add-on is distributed under Apache License 2.0. For license terms, see LICENSE.txt.
 
-TEMPLATE_ADDON is written by Flowing Code S.A.
+Image Crop Add-on is written by Flowing Code S.A.
 
 # Developer Guide
 
 ## Getting started
 
-Add your code samples in this section
+* Basic use
+
+```java
+Image image = new Image("images/empty-plant.png", "image to crop");  
+ImageCrop imageCrop = new ImageCrop(image);
+add(imageCrop);
+```
+
+* Get cropped image 
+
+```java
+Image croppedImage = new Image(imageCrop.getCroppedImageDataUri(), "cropped image")
+```
 
 ## 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 add-on might need to be whitelisted in order to display correctly. 
 
-To do so, just add ```com.flowingcode``` to the ```vaadin.whitelisted-packages``` property in ```src/main/resources/application.properties```, like:
+To do so, just add ```com.flowingcode``` to the ```vaadin.allowed-packages``` property in ```src/main/resources/application.properties```, like:
 
-```vaadin.whitelisted-packages = com.vaadin,org.vaadin,dev.hilla,com.flowingcode```
+```vaadin.allowed-packages = com.vaadin,org.vaadin,dev.hilla,com.flowingcode```
 
 More information on Spring whitelisted configuration [here](https://vaadin.com/docs/latest/integrations/spring/configuration/#configure-the-scanning-of-packages).

pom.xml

@@ -5,22 +5,22 @@
     <modelVersion>4.0.0</modelVersion>
 
     <groupId>com.flowingcode.vaadin.addons</groupId>
-    <artifactId>template-addon</artifactId>
+    <artifactId>image-crop-addon</artifactId>
     <version>1.0.0-SNAPSHOT</version>
-    <name>Template Add-on</name>
-    <description>Template Add-on for Vaadin Flow</description>
+    <name>Image Crop Add-on</name>
+    <description>Image Crop Add-on for Vaadin Flow</description>
     <url>https://www.flowingcode.com/en/open-source/</url>
 
     <properties>
-        <vaadin.version>24.3.0</vaadin.version>
+        <vaadin.version>24.4.6</vaadin.version>
         <selenium.version>4.10.0</selenium.version>
         <maven.compiler.source>17</maven.compiler.source>
         <maven.compiler.target>17</maven.compiler.target>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
         <drivers.dir>${project.basedir}/drivers</drivers.dir>
-        <jetty.version>11.0.12</jetty.version>
-        <flowingcode.commons.demo.version>3.9.0</flowingcode.commons.demo.version>
+        <jetty.version>11.0.21</jetty.version>
+        <flowingcode.commons.demo.version>4.1.0</flowingcode.commons.demo.version>
         <frontend.hotdeploy>true</frontend.hotdeploy>
     </properties>
 
@@ -29,7 +29,7 @@
         <url>https://www.flowingcode.com</url>
     </organization>
 
-    <inceptionYear>2023</inceptionYear>
+    <inceptionYear>2024</inceptionYear>
     <licenses>
         <license>
             <name>Apache 2</name>
@@ -39,9 +39,9 @@
     </licenses>
 
     <scm>
-        <url>https://github.com/FlowingCode/AddonStarter24</url>
-        <connection>scm:git:git://github.com/FlowingCode/AddonStarter24.git</connection>
-        <developerConnection>scm:git:ssh://[email protected]:/FlowingCode/AddonStarter24.git</developerConnection>
+        <url>https://github.com/FlowingCode/ImageCrop</url>
+        <connection>scm:git:git://github.com/FlowingCode/ImageCrop.git</connection>
+        <developerConnection>scm:git:ssh://[email protected]:/FlowingCode/ImageCrop.git</developerConnection>
         <tag>master</tag>
     </scm>
 
@@ -156,6 +156,12 @@
             <version>5.1.1</version>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <version>3.12.4</version>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <build>
@@ -254,7 +260,7 @@
                 <artifactId>jetty-maven-plugin</artifactId>
                 <version>${jetty.version}</version>
                 <configuration>
-                    <scanIntervalSeconds>3</scanIntervalSeconds>
+                    <scan>3</scan>
                     <!-- Use test scope because the UI/demo classes are in the test package. -->
                     <useTestScope>true</useTestScope>
                     <webApp>
@@ -363,7 +369,7 @@
                         <artifactId>jetty-maven-plugin</artifactId>
                         <version>${jetty.version}</version>
                         <configuration>
-                            <scanIntervalSeconds>0</scanIntervalSeconds>
+                            <scan>0</scan>
                             <supportedPackagings>
                                 <supportedPackaging>jar</supportedPackaging>
                             </supportedPackagings>

src/main/java/com/flowingcode/vaadin/addons/imagecrop/Crop.java

@@ -0,0 +1,50 @@
+/*-
+ * #%L
+ * Image Crop Add-on
+ * %%
+ * Copyright (C) 2024 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.imagecrop;
+
+/**
+ * Represents crop dimensions.
+ * <p>
+ * The crop dimensions are defined by the unit, x and y coordinates, width, and
+ * height.
+ *
+ * @param unit   the unit of the crop dimensions, can be 'px' (pixels) or '%'
+ *               (percentage).
+ * @param x      the x-coordinate of the cropped area.
+ * @param y      the y-coordinate of the cropped area.
+ * @param width  the width of the cropped area
+ * @param height the height of the cropped area
+ */
+public record Crop(String unit, int x, int y, int width, int height) {
+
+    /**
+     * Returns a string representation of the Crop object.
+     *
+     * @return A string representing the crop dimensions in the format:
+     *         "{ unit: %s, x: %s, y: %s, width: %s, height: %s }"
+     *         where %s is replaced by the corresponding value.
+     */
+    @Override
+    public final String toString() {
+        return "{ unit: %s, x: %s, y: %s, width: %s, height: %s }".formatted(unit, x, y, width, height);
+    }
+
+}

src/main/java/com/flowingcode/vaadin/addons/imagecrop/CroppedImageEvent.java

@@ -0,0 +1,57 @@
+/*-
+ * #%L
+ * Image Crop Add-on
+ * %%
+ * Copyright (C) 2024 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.imagecrop;
+
+import com.vaadin.flow.component.ComponentEvent;
+import com.vaadin.flow.component.DomEvent;
+import com.vaadin.flow.component.EventData;
+
+/**
+ * Represents an event triggered when an image is cropped and encoded.
+ */
+@DomEvent("cropped-image")
+public class CroppedImageEvent extends ComponentEvent<ImageCrop> {
+
+  private String croppedImageDataUri;
+
+  /**
+   * Constructs a new CroppedImageEvent.
+   *
+   * @param source the source of the event
+   * @param fromClient <code>true</code> if the event originated from the client-side,
+   *        <code>false</code> otherwise
+   * @param croppedImageDataUri the data URL of the cropped image
+   */
+  public CroppedImageEvent(ImageCrop source, boolean fromClient,
+      @EventData("event.detail.croppedImageDataUri") String croppedImageDataUri) {
+    super(source, fromClient);
+    this.croppedImageDataUri = croppedImageDataUri;
+  }
+
+  /**
+   * Returns the cropped image data URL.
+   *
+   * @return the cropped image data URL
+   */
+  public String getCroppedImageDataUri() {
+    return this.croppedImageDataUri;
+  }
+}