Release 0.15.0 ready (#420)

* #412 #414 #415 #416 done

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: vaadin-miki <vaadin-miki@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

README.md

@@ -23,7 +23,7 @@ This is the relevant dependency:
 <dependency>
    <groupId>org.vaadin.miki</groupId>
    <artifactId>superfields</artifactId>
-   <version>0.14.1</version>
+   <version>0.15.0</version>
 </dependency>
 ```
 
@@ -62,6 +62,7 @@ The author of the majority of the code is Miki, but this project would not be po
 * Jean-Christophe Gueriaud
 * Holger Hähnel
 * Matthias Hämmerle
+* Jarmo Kemppainen
 * Gerald Koch
 * Sebastian Kühnau
 * Jean-François Lamy

demo-v23/pom.xml

@@ -4,11 +4,11 @@
     <parent>
         <artifactId>superfields-parent</artifactId>
         <groupId>org.vaadin.miki</groupId>
-        <version>0.14.1</version>
+        <version>0.15.0</version>
     </parent>
 
     <artifactId>superfields-demo-v23</artifactId>
-    <version>0.14.1</version>
+    <version>0.15.0</version>
     <name>V23+ demo app for SuperFields</name>
     <description>Showcase application for V23+ and SuperFields.</description>
     <packaging>war</packaging>
@@ -23,7 +23,7 @@
         <dependency>
             <groupId>org.vaadin.miki</groupId>
             <artifactId>superfields</artifactId>
-            <version>0.14.1</version>
+            <version>0.15.0</version>
         </dependency>
         <dependency>
             <groupId>javax.servlet</groupId>

demo-v23/src/main/java/org/vaadin/miki/demo/builders/HasPositionableLabelBuilder.java

@@ -0,0 +1,25 @@
+package org.vaadin.miki.demo.builders;
+
+import com.vaadin.flow.component.Component;
+import com.vaadin.flow.component.combobox.ComboBox;
+import org.vaadin.miki.demo.ContentBuilder;
+import org.vaadin.miki.demo.Order;
+import org.vaadin.miki.markers.HasLabelPositionable;
+import org.vaadin.miki.shared.labels.LabelPosition;
+
+import java.util.function.Consumer;
+
+/**
+ * @author miki
+ * @since 2022-09-23
+ */
+@Order(33)
+public class HasPositionableLabelBuilder implements ContentBuilder<HasLabelPositionable> {
+    @Override
+    public void buildContent(HasLabelPositionable component, Consumer<Component[]> callback) {
+        final ComboBox<LabelPosition> positions = new ComboBox<>("Pick label position:", LabelPosition.values());
+        positions.setAllowCustomValue(false);
+        positions.addValueChangeListener(event -> component.setLabelPosition(event.getValue()));
+        callback.accept(new Component[]{positions});
+    }
+}

demo-v23/src/main/java/org/vaadin/miki/demo/builders/ObjectFieldBuilder.java

@@ -12,7 +12,7 @@
 import java.time.LocalDate;
 import java.util.function.Consumer;
 
-@Order(61)
+@Order(1)
 public class ObjectFieldBuilder implements ContentBuilder<ObjectField<Book>> {
     @Override
     public void buildContent(ObjectField<Book> component, Consumer<Component[]> callback) {

demo-v23/src/main/java/org/vaadin/miki/demo/builders/VariantFieldBuilder.java

@@ -17,7 +17,7 @@
  * @author miki
  * @since 2022-04-11
  */
-@Order(80)
+@Order(1)
 public class VariantFieldBuilder implements ContentBuilder<VariantField> {
 
     @Override

demo-v23/src/main/java/org/vaadin/miki/demo/providers/CollectionFieldProvider.java

@@ -32,7 +32,10 @@ public CollectionField<String, List<String>> getComponent() {
                         ),
                         Collections.singletonList(CollectionComponentProviders.addLastButton("Add as last"))),
                 CollectionComponentProviders.rowWithRemoveButtonFirst(CollectionComponentProviders.labelledField(SuperTextField::new, "Value"), "Remove")
-        ).withHelperText("(validator requires precisely three elements)");
+        )
+                .withHelperText("(validator requires precisely three elements)")
+                .withLabel("Enter some words:")
+                ;
     }
 
     @Override

demo-v23/src/main/java/org/vaadin/miki/demo/providers/GridMultiSelectProvider.java

@@ -15,7 +15,9 @@ public class GridMultiSelectProvider implements ComponentProvider<GridMultiSelec
     @Override
     public GridMultiSelect<SuperFieldsGridItem> getComponent() {
         final GridMultiSelect<SuperFieldsGridItem> gridSelect = new GridMultiSelect<>(SuperFieldsGridItem.class, true, SuperFieldsGridItem.getAllRegisteredProviders())
-                .withHelperText("(you can select multiple rows)");
+                .withHelperText("(you can select multiple rows)")
+                .withLabel("Choose as many as you like:")
+                ;
         gridSelect.getGrid().getColumnByKey("nameLength").setAutoWidth(true);
         return gridSelect;
     }

demo-v23/src/main/java/org/vaadin/miki/demo/providers/GridSelectProvider.java

@@ -15,7 +15,8 @@ public class GridSelectProvider implements ComponentProvider<GridSelect<SuperFie
     @Override
     public GridSelect<SuperFieldsGridItem> getComponent() {
         final GridSelect<SuperFieldsGridItem> gridSelect = new GridSelect<>(SuperFieldsGridItem.class, true, SuperFieldsGridItem.getAllRegisteredProviders())
-                .withHelperText("(at most one row can be selected)");
+                .withHelperText("(at most one row can be selected)")
+                .withLabel("Please select your favourite component:");
         gridSelect.getGrid().getColumnByKey("nameLength").setAutoWidth(true);
         return gridSelect;
     }

demo-v23/src/main/java/org/vaadin/miki/demo/providers/MapFieldProvider.java

@@ -34,6 +34,8 @@ public MapField<String, Integer> getComponent() {
                             () -> new SuperTextField("Any text:"),
                                 () -> new SuperIntegerField("Any integer:")
                 ), "Remove"))
-                .withHelperText("(this is a Map<String, Integer>)");
+                .withHelperText("(this is a Map<String, Integer>)")
+                .withLabel("Please enter key-value data:")
+                ;
     }
 }

demo-v23/src/main/java/org/vaadin/miki/demo/providers/ObjectFieldProvider.java

@@ -36,7 +36,8 @@ public ObjectFieldProvider() {
     @Override
     public ObjectField<Book> getComponent() {
         return this.factory.buildAndConfigureObjectField(Book.class)
-                .withHelperText("(this field with all its components is automatically generated from a model class)")
-                .withHelperAbove();
+                .withHelperText("(this entire form with all its components is automatically generated from a model class)")
+                .withLabel("Book details:")
+                ;
     }
 }

demo-v23/src/main/java/org/vaadin/miki/demo/providers/SuperCheckboxProvider.java

@@ -0,0 +1,18 @@
+package org.vaadin.miki.demo.providers;
+
+import org.vaadin.miki.demo.ComponentProvider;
+import org.vaadin.miki.demo.Order;
+import org.vaadin.miki.superfields.checkbox.SuperCheckbox;
+
+/**
+ * Provides a fresh {@link SuperCheckbox}.
+ * @author miki
+ * @since 2022-09-15
+ */
+@Order(99)
+public class SuperCheckboxProvider implements ComponentProvider<SuperCheckbox> {
+    @Override
+    public SuperCheckbox getComponent() {
+        return new SuperCheckbox().withLabel("This component can be made read-only, contrary to the original Checkbox.");
+    }
+}

demo-v23/src/main/resources/SuperCheckbox.md

@@ -0,0 +1 @@
+A fixed version of the regular `Checkbox` - can be set to read-only and can have a title.

pom.xml

@@ -3,7 +3,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>org.vaadin.miki</groupId>
     <artifactId>superfields-parent</artifactId>
-    <version>0.14.1</version>
+    <version>0.15.0</version>
     <modules>
         <module>superfields</module>
         <module>demo-v23</module>

superfields/README.md

@@ -26,6 +26,10 @@ Some components contain server-side methods to control text selection in their w
 
 The web components listen to each key press and mouse click. If text selection changes as a result of that action, they send an event to the server-side component. This may happen quite often and increase server load, so the feature is turned off by default. To turn it on simply call `setReceivingSelectionEventsFromClient(true)` (or `withReceivingSelectionEventsFromClient(true)`).  
 
+#### Label position
+
+Most of the components that can have a label allow positioning said label through `setLabelPosition(...)` (or `withLabelPosition(...)`). This should work in most layouts, with `FormLayout` being an obvious exception. Not all components support all possible values of `LabelPosition` (`SuperCheckbox` ignores vertical alignment). In addition, things might work weird when using right-to-left languages - if that happens, please report the problem in GitHub.
+
 #### Log messages
 
 Quite a few components log their state using [SLF4J](https://www.slf4j.org). Critical information is logged as error or warning, debugging messages are, well, debug or trace. Information about [how to configure which log messages get displayed can be found e.g. on Stack Overflow](https://stackoverflow.com/questions/45997759/how-to-change-slf4j-logging-level).

superfields/pom.xml

@@ -8,7 +8,7 @@
     <artifactId>superfields</artifactId>
     <name>SuperFields</name>
     <description>Code for various V14+ fields and other components.</description>
-    <version>0.14.1</version>
+    <version>0.15.0</version>
 
     <properties>
         <maven.compiler.source>11</maven.compiler.source>

superfields/release-notes.md

@@ -1,3 +1,12 @@
+# 0.15.0 - HasPositionableLabel
+## New features and enhancements
+* \#414 - [Positionable component labels](https://github.com/vaadin-miki/super-fields/issues/414)
+## Changes to API
+* \#412 - [SuperCheckbox should implement relevant marker interfaces](https://github.com/vaadin-miki/super-fields/issues/412)
+* \#415 - [CollectionField and Grid(Multi)Select should implement HasLabel](https://github.com/vaadin-miki/super-fields/issues/415)
+## Bug fixes
+* \#415 - [CollectionField and Grid(Multi)Select should implement HasLabel](https://github.com/vaadin-miki/super-fields/issues/415)
+* \#416 - [SuperCheckbox gets out of sync](https://github.com/vaadin-miki/super-fields/issues/416)
 # 0.14.1 - SuperCheckbox and bugfixes
 ## New features and enhancements
 * \#400 - [ObjectField should support enums and other values presentable with ComboBox](https://github.com/vaadin-miki/super-fields/issues/400)

superfields/src/main/java/org/vaadin/miki/markers/HasLabelPositionable.java

@@ -0,0 +1,48 @@
+package org.vaadin.miki.markers;
+
+import com.vaadin.flow.component.HasElement;
+import org.vaadin.miki.shared.labels.LabelPosition;
+
+/**
+ * Marker interface for components that have a positionable label.
+ *
+ * @author miki
+ * @since 2022-09-23
+ */
+public interface HasLabelPositionable extends HasElement {
+
+    /**
+     * Attribute name that contains the selected label position value.
+     */
+    String LABEL_POSITION_ATTRIBUTE = "data-label-position";
+    /**
+     * Attribute name that contains details of the label for easy styling.
+     */
+    String LABEL_POSITION_DETAILS_ATTRIBUTE = "data-label-position-details";
+
+    /**
+     * Sets the label position to a new one.
+     * @param position A position to use. Setting {@code null} will reset it to the default setting.
+     */
+    default void setLabelPosition(LabelPosition position) {
+        if(position == null || position == LabelPosition.DEFAULT) {
+            this.getElement().removeAttribute(LABEL_POSITION_ATTRIBUTE);
+            this.getElement().removeAttribute(LABEL_POSITION_DETAILS_ATTRIBUTE);
+        }
+        else {
+            this.getElement().setAttribute(LABEL_POSITION_ATTRIBUTE, position.name());
+            this.getElement().setAttribute(LABEL_POSITION_DETAILS_ATTRIBUTE, position.getPositionData());
+        }
+    }
+
+    /**
+     * Returns current label position, if it has been set.
+     * @return A {@link LabelPosition}.
+     */
+    default LabelPosition getLabelPosition() {
+        if(this.getElement().hasAttribute(LABEL_POSITION_ATTRIBUTE))
+            return LabelPosition.valueOf(this.getElement().getAttribute(LABEL_POSITION_ATTRIBUTE));
+        else return LabelPosition.DEFAULT;
+    }
+
+}

superfields/src/main/java/org/vaadin/miki/markers/WithLabelPositionableMixin.java

@@ -0,0 +1,23 @@
+package org.vaadin.miki.markers;
+
+import org.vaadin.miki.shared.labels.LabelPosition;
+
+/**
+ * A mixin for {@link HasLabelPositionable}.
+ *
+ * @author miki
+ * @since 2022-09-23
+ */
+public interface WithLabelPositionableMixin<SELF extends HasLabelPositionable> extends HasLabelPositionable {
+
+    /**
+     * Chains {@link #setLabelPosition(LabelPosition)} and returns itself.
+     * @param position Position.
+     * @return This.
+     */
+    @SuppressWarnings("unchecked")
+    default SELF withLabelPosition(LabelPosition position) {
+        this.setLabelPosition(position);
+        return (SELF) this;
+    }
+}

superfields/src/main/java/org/vaadin/miki/shared/labels/LabelPosition.java

@@ -0,0 +1,77 @@
+package org.vaadin.miki.shared.labels;
+
+import java.util.Locale;
+
+/**
+ * Available label positions.
+ *
+ * @author miki
+ * @since 2022-09-23
+ */
+public enum LabelPosition {
+
+    /**
+     * Default label position, without any changes.
+     */
+    DEFAULT(false),
+
+    /**
+     * Label is placed to the side of the component, before it, and aligned to the start of the column.
+     * In left-to-right, top-to-bottom layouts, this means: label on the left, aligned to the top.
+     */
+    BEFORE_START,
+    /**
+     * Label is placed to the side of the component, before it, and aligned to the middle of the column.
+     * In left-to-right, top-to-bottom layouts, this means: label on the left, in the vertical middle of column.
+     */
+    BEFORE_MIDDLE,
+    /**
+     * Label is placed to the side of the component, before it, and aligned to the end of the column.
+     * In left-to-right, top-to-bottom layouts, this means: label on the left, aligned to the bottom.
+     */
+    BEFORE_END,
+    /**
+     * Label is placed to the side of the component, after it, and aligned to the start of the column.
+     * In left-to-right, top-to-bottom layouts, this means: label on the right, aligned to the top.
+     */
+    AFTER_START,
+    /**
+     * Label is placed to the side of the component, after it, and aligned to the middle of the column.
+     * In left-to-right, top-to-bottom layouts, this means: label on the right, in the vertical middle of column.
+     */
+    AFTER_MIDDLE,
+    /**
+     * Label is placed to the side of the component, after it, and aligned to the end of the column.
+     * In left-to-right, top-to-bottom layouts, this means: label on the right, aligned to the bottom.
+     */
+    AFTER_END,
+    /**
+     * Label is placed as the last thing of the entire component.
+     * In left-to-right, top-to-bottom layouts, this means: label on the bottom.
+     */
+    LAST(false);
+
+    private final String positionData;
+
+    LabelPosition() {
+        this(true);
+    }
+
+    /**
+     * Creates the enum.
+     * @param side Whether the label is on the side of the component.
+     */
+    LabelPosition(boolean side) {
+        this.positionData = String.join(" ", ((side ? "side_" : "") + this.name()).toLowerCase(Locale.ROOT).split("_"));
+    }
+
+    /**
+     * The attribute value that corresponds to the given label position. Used by CSS selectors.
+     * This is a space-separated list of styles. Never {@code null}.
+     *
+     * @return A non-{@code null} array.
+     */
+    public String getPositionData() {
+        return positionData;
+    }
+}