Mixins and javadocs cleaned up

demo-v14/src/main/java/org/vaadin/miki/demo/builders/HasCollectionValueComponentProviderBuilder.java

@@ -6,7 +6,7 @@
 import org.vaadin.miki.demo.Order;
 import org.vaadin.miki.superfields.collections.CollectionField;
 import org.vaadin.miki.superfields.collections.CollectionValueComponentProvider;
-import org.vaadin.miki.superfields.collections.IndexedButton;
+import org.vaadin.miki.superfields.buttons.IndexedButton;
 import org.vaadin.miki.superfields.text.SuperTextField;
 import org.vaadin.miki.superfields.util.CollectionComponentProviders;
 

demo-v14/src/main/java/org/vaadin/miki/demo/builders/HasTitleBuilder.java

@@ -0,0 +1,25 @@
+package org.vaadin.miki.demo.builders;
+
+import com.vaadin.flow.component.Component;
+import org.vaadin.miki.demo.ContentBuilder;
+import org.vaadin.miki.demo.Order;
+import org.vaadin.miki.markers.HasTitle;
+import org.vaadin.miki.superfields.text.SuperTextField;
+
+import java.util.function.Consumer;
+
+/**
+ * Builds content for anything that implements {@link HasTitle}.
+ * @author miki
+ * @since 2021-09-13
+ */
+@Order(118)
+public class HasTitleBuilder implements ContentBuilder<HasTitle> {
+
+    @Override
+    public void buildContent(HasTitle component, Consumer<Component[]> callback) {
+        final SuperTextField title = new SuperTextField("Title (tooltip) of the component: ");
+        title.addValueChangeListener(event -> component.setTitle(event.getValue()));
+        callback.accept(new Component[]{title});
+    }
+}

demo-v14/src/main/java/org/vaadin/miki/demo/builders/WithMaximumSelectionSizeBuilder.java

@@ -5,20 +5,20 @@
 import org.vaadin.miki.demo.ContentBuilder;
 import org.vaadin.miki.demo.Order;
 import org.vaadin.miki.markers.HasMaximumSelectionSize;
-import org.vaadin.miki.markers.WithMaximumSelectionSize;
+import org.vaadin.miki.markers.WithMaximumSelectionSizeMixin;
 
 import java.util.function.Consumer;
 
 /**
- * Builds content for {@link WithMaximumSelectionSize}.
+ * Builds content for {@link WithMaximumSelectionSizeMixin}.
  * @author miki
  * @since 2020-12-09
  */
 @Order(160)
-public class WithMaximumSelectionSizeBuilder implements ContentBuilder<WithMaximumSelectionSize<?>> {
+public class WithMaximumSelectionSizeBuilder implements ContentBuilder<WithMaximumSelectionSizeMixin<?>> {
 
     @Override
-    public void buildContent(WithMaximumSelectionSize<?> component, Consumer<Component[]> callback) {
+    public void buildContent(WithMaximumSelectionSizeMixin<?> component, Consumer<Component[]> callback) {
         final ComboBox<Integer> selectionSize = new ComboBox<>("Maximum allowed selection size:",
                 HasMaximumSelectionSize.UNLIMITED, 1, 2, 3, 4, 5, 6);
         selectionSize.addValueChangeListener(event -> component.setMaximumSelectionSize(event.getValue()));

demo-v14/src/main/java/org/vaadin/miki/demo/builders/WithNullValueOptionallyAllowedBuilder.java

@@ -4,20 +4,20 @@
 import com.vaadin.flow.component.checkbox.Checkbox;
 import org.vaadin.miki.demo.ContentBuilder;
 import org.vaadin.miki.demo.Order;
-import org.vaadin.miki.markers.WithNullValueOptionallyAllowed;
+import org.vaadin.miki.markers.WithNullValueOptionallyAllowedMixin;
 
 import java.util.function.Consumer;
 
 /**
- * Builds content for {@link WithNullValueOptionallyAllowed}.
+ * Builds content for {@link WithNullValueOptionallyAllowedMixin}.
  * @author miki
  * @since 2020-11-19
  */
 @Order(40)
-public class WithNullValueOptionallyAllowedBuilder implements ContentBuilder<WithNullValueOptionallyAllowed<?, ?, ?>> {
+public class WithNullValueOptionallyAllowedBuilder implements ContentBuilder<WithNullValueOptionallyAllowedMixin<?, ?, ?>> {
 
     @Override
-    public void buildContent(WithNullValueOptionallyAllowed<?, ?, ?> component, Consumer<Component[]> callback) {
+    public void buildContent(WithNullValueOptionallyAllowedMixin<?, ?, ?> component, Consumer<Component[]> callback) {
         final Checkbox allow = new Checkbox("Allow empty string as null value?", event -> component.setNullValueAllowed(event.getValue()));
         callback.accept(new Component[]{allow});
     }

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

@@ -0,0 +1,31 @@
+package org.vaadin.miki.markers;
+
+import com.vaadin.flow.component.HasValue;
+
+/**
+ * Marker interface for descendants of {@link HasValue} that may optionally allow {@code null} as value.
+ * By default, objects should not allow {@code null}s.
+ * In general, when this feature is turned on and {@link #setValue(Object)} is called with {@code null}, the
+ * object should never throw a {@link NullPointerException}.
+ *
+ * @param <E> Event type.
+ * @param <V> Value type.
+ *
+ * @author miki
+ * @since 2021-09-13
+ */
+public interface HasNullValueOptionallyAllowed<E extends HasValue.ValueChangeEvent<V>, V> extends HasValue<E, V> {
+
+    /**
+     * Checks whether {@code null} is allowed as a value of the component.
+     * @return Whether {@code null} is allowed as a value. Should default to {@code false}.
+     */
+    boolean isNullValueAllowed();
+
+    /**
+     * Sets allowance of {@code null} as this component's value.
+     * @param allowingNullValue Whether to allow {@code null} as a value.
+     */
+    void setNullValueAllowed(boolean allowingNullValue);
+
+}

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

@@ -14,6 +14,7 @@ public interface WithComponentAsIconMixin<SELF extends HasComponentAsIcon> exten
      * Chains {@link #setIcon(Component)} and returns itself.
      * @param icon Icon to set. Can be {@code null}.
      * @return This.
+     * @see #setIcon(Component)
      */
     @SuppressWarnings("unchecked")
     default SELF withIcon(Component icon) {

superfields/src/main/java/org/vaadin/miki/markers/WithHelper.java → superfields/src/main/java/org/vaadin/miki/markers/WithHelperMixin.java

@@ -9,12 +9,13 @@
  * @author miki
  * @since 2020-10-12
  */
-public interface WithHelper<SELF extends HasHelper> extends HasHelper {
+public interface WithHelperMixin<SELF extends HasHelper> extends HasHelper {
 
     /**
      * Chains {@link #setHelperText(String)} and returns itself.
      * @param helperText Helper text to set.
      * @return This.
+     * @see #setHelperText(String)
      */
     @SuppressWarnings("unchecked")
     default SELF withHelperText(String helperText) {
@@ -26,6 +27,7 @@ default SELF withHelperText(String helperText) {
      * Chains {@link #setHelperComponent(Component)} and returns itself.
      * @param component Helper component to use.
      * @return This.
+     * @see #setHelperComponent(Component)
      */
     @SuppressWarnings("unchecked")
     default SELF withHelperComponent(Component component) {

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

@@ -14,6 +14,7 @@ public interface WithIconMixin<SELF extends HasIcon> extends HasIcon {
      * Chains {@link #setIcon(Icon)} and returns itself.
      * @param icon Icon to set.
      * @return This.
+     * @see #setIcon(Icon)
      */
     @SuppressWarnings("unchecked")
     default SELF withIcon(Icon icon) {

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

@@ -12,6 +12,7 @@ public interface WithIdMixin<SELF extends HasId> extends HasId {
      * Chains setting id.
      * @param id Id to set.
      * @return This.
+     * @see #setId(String)
      */
     @SuppressWarnings("unchecked")
     default SELF withId(String id) {

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

@@ -13,6 +13,7 @@ public interface WithIndexMixin<SELF extends HasIndex> extends HasIndex {
      * Chains {@link #setIndex(int)} and returns itself.
      * @param index Index to set.
      * @return This.
+     * @see #setIndex(int)
      */
     @SuppressWarnings("unchecked")
     default SELF withIndex(int index) {

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

@@ -9,13 +9,16 @@
  * Mixin interface to allow chaining of setting items.
  * @param <T> Type of items to add.
  * @param <SELF> Self type.
+ * @author miki
+ * @since 2020-04-30
  */
 public interface WithItemsMixin<T, SELF extends HasItems<T>> extends HasItems<T> {
 
     /**
      * Chains {@link #setItems(Object[])} and returns itself.
      * @param items Items to add.
      * @return This.
+     * @see #setItems(Object[])
      */
     @SuppressWarnings("unchecked")
     default SELF withItems(T... items) {
@@ -27,6 +30,7 @@ default SELF withItems(T... items) {
      * Chains {@link #setItems(Collection)} and returns itself.
      * @param items Items to add.
      * @return This.
+     * @see #setItems(Collection)
      */
     @SuppressWarnings("unchecked")
     default SELF withItems(Collection<T> items) {
@@ -38,6 +42,7 @@ default SELF withItems(Collection<T> items) {
      * Chains {@link #setItems(Stream)} and returns itself.
      * @param items Items to add.
      * @return This.
+     * @see #setItems(Stream)
      */
     @SuppressWarnings("unchecked")
     default SELF withItems(Stream<T> items) {

superfields/src/main/java/org/vaadin/miki/markers/WithMaximumSelectionSize.java → superfields/src/main/java/org/vaadin/miki/markers/WithMaximumSelectionSizeMixin.java

@@ -6,7 +6,7 @@
  * @author miki
  * @since 2020-12-09
  */
-public interface WithMaximumSelectionSize<SELF extends HasMaximumSelectionSize> extends HasMaximumSelectionSize {
+public interface WithMaximumSelectionSizeMixin<SELF extends HasMaximumSelectionSize> extends HasMaximumSelectionSize {
 
     /**
      * Chains {@link #setMaximumSelectionSize(int)} and returns itself.

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

@@ -0,0 +1,25 @@
+package org.vaadin.miki.markers;
+
+import com.vaadin.flow.component.HasValue;
+
+/**
+ * Mixin interface for {@link HasNullValueOptionallyAllowed}.
+ *
+ * @author miki
+ * @since 2020-06-09
+ */
+public interface WithNullValueOptionallyAllowedMixin<SELF extends HasNullValueOptionallyAllowed<E, V>, E extends HasValue.ValueChangeEvent<V>, V> extends HasNullValueOptionallyAllowed<E, V> {
+
+    /**
+     * Chains {@link #setNullValueAllowed(boolean)} and returns itself.
+     * @param allowingNullValue Whether to allow {@code null} as a value.
+     * @return This.
+     * @see #setNullValueAllowed(boolean)
+     */
+    @SuppressWarnings("unchecked")
+    default SELF withNullValueAllowed(boolean allowingNullValue) {
+        this.setNullValueAllowed(allowingNullValue);
+        return (SELF)this;
+    }
+
+}

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

@@ -14,6 +14,7 @@ public interface WithTextMixin<SELF extends HasText> extends HasText {
      * Chains {@link #setText(String)} and returns itself.
      * @param text Text to set.
      * @return This.
+     * @see #setText(String)
      */
     @SuppressWarnings("unchecked")
     default SELF withText(String text) {