Add HasHelper interface (#8922)

* Add HasHelper interface (#8532)

flow-server/src/main/java/com/vaadin/flow/component/HasHelper.java

@@ -0,0 +1,98 @@
+/*
+ * Copyright 2000-2020 Vaadin Ltd.
+ *
+ * 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.
+ */
+package com.vaadin.flow.component;
+
+import java.util.Optional;
+
+import com.vaadin.flow.dom.Element;
+
+/**
+ * Mixin interface for field components that have helper text as property and
+ * slots for inserting components.
+ *
+ * @author Vaadin Ltd
+ * @since 2.4
+ */
+public interface HasHelper extends HasElement {
+  /**
+   * String used for the helper text.
+   *
+   * @return the {@code helperText} property from the web component
+   */
+  default String getHelperText() {
+    return getElement().getProperty("helperText");
+  }
+
+  /**
+   * <p>
+   * String used for the helper text. It shows a text adjacent to the field that
+   * can be used, e.g., to inform to the users which values it expects. Example:
+   * a text "The password must contain numbers" for the PasswordField.
+   * </p>
+   * 
+   * <p>
+   * In case both {@link #setHelperText(String)} and
+   * {@link #setHelperComponent(Component)} are used, only the element defined
+   * by {@link #setHelperComponent(Component)} will be visible, regardless of
+   * the order on which they are defined.
+   * </p>
+   *
+   * @param helperText
+   *            the String value to set
+   */
+  default void setHelperText(String helperText) {
+    getElement().setProperty("helperText", helperText);
+  }
+  /**
+   * Adds the given component into helper slot of component, replacing any
+   * existing helper component. It adds the component adjacent to the field that
+   * can be used, e.g., to inform to the users which values it expects. Example:
+   * a component that shows the password strength for the PasswordField.
+   * 
+   * @param component
+   *            the component to set, can be {@code null} to remove existing
+   *            helper component
+   * 
+   * @see #setHelperText(String)
+   */
+  default void setHelperComponent(Component component) {
+    getElement().getChildren()
+      .filter(child -> "helper".equals(child.getAttribute("slot")))
+      .findAny()
+      .ifPresent(getElement()::removeChild);
+
+    if (component != null) {
+        component.getElement().setAttribute("slot", "helper");
+        getElement().appendChild(component.getElement());
+    }
+  }
+
+  /**
+   * Gets the component in the helper slot of this field.
+   * 
+   * @return the helper component of this field, or {@code null} if no helper
+   *         component has been set
+   * @see #setHelperComponent(Component)
+   */
+  default Component getHelperComponent() {
+    Optional<Component> component = getElement().getChildren()
+      .filter(child -> "helper".equals(child.getAttribute("slot")))
+      .map(Element::getComponent)
+      .findFirst().orElse(Optional.empty());
+
+    return component.orElse(null);
+  }
+}

flow-server/src/test/java/com/vaadin/flow/component/HasHelperTest.java

@@ -0,0 +1,75 @@
+/*
+ * Copyright 2000-2020 Vaadin Ltd.
+ *
+ * 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.
+ */
+package com.vaadin.flow.component;
+
+import org.junit.Assert;
+import org.junit.Test;
+
+public class HasHelperTest {
+
+    @Tag("div")
+    public static class HasHelperComponent extends Component implements HasHelper {
+    }
+
+    @Test
+    public void getHelperText() {
+        final HasHelperComponent c = new HasHelperComponent();
+        Assert.assertNull(c.getHelperText());
+    }
+
+    @Test
+    public void getHelperComponent() {
+        final HasHelperComponent c = new HasHelperComponent();
+        Assert.assertNull(c.getHelperComponent());
+    }
+
+    @Test
+    public void setHelperText() {
+        final HasHelperComponent c = new HasHelperComponent();
+        c.setHelperText("helper");
+        Assert.assertEquals("helper", c.getHelperText());
+    }
+
+    @Test
+    public void setHelperComponent() {
+        final HasHelperComponent c = new HasHelperComponent();
+        final HasHelperComponent slotted = new HasHelperComponent();
+        c.setHelperComponent(slotted);
+        Assert.assertEquals(slotted, c.getHelperComponent());
+    }
+
+    @Test
+    public void removeHelperText() {
+        final HasHelperComponent c = new HasHelperComponent();
+        c.setHelperText("helper");
+        Assert.assertEquals("helper", c.getHelperText());
+
+        c.setHelperText(null);
+        Assert.assertNull(c.getHelperText());
+    }
+
+    @Test
+    public void removeHelperComponent() {
+        final HasHelperComponent c = new HasHelperComponent();
+        final HasHelperComponent slotted = new HasHelperComponent();
+
+        c.setHelperComponent(slotted);
+        Assert.assertEquals(slotted, c.getHelperComponent());
+
+        c.setHelperComponent(null);
+        Assert.assertNull(c.getHelperComponent());
+    }
+}