feat: add API to set spacing in HL/VL with custom values (#7129)

* feat: add API to set spacing in HL/VL with custom values

This changes adds:
- `setSpacing(String)` - method to set spacing passing a CSS lenght
value (e.g. `10px`, `1em`)
- `setSpacing(float, Unit)` - method to set spacing passing a float
value and a `Unit`
- `getSpacing()` - method to return the value set to the `gap` CSS
property of the layout

It also changes `isSpacing()` to return whether the spacing has been set
by the theme API or by setting the `gap` property.

* chore: apply format

* fix: use gap instead of private CSS variable

* refactor: remove code not needed

* docs: enhance getSpacing documentation

* test: add test to check setSpacing(false)

---------

Co-authored-by: Zhe Sun <[email protected]>
Co-authored-by: Sascha Ißbrücker <[email protected]>

Author: 3 people

vaadin-ordered-layout-flow-parent/vaadin-ordered-layout-flow/src/main/java/com/vaadin/flow/component/orderedlayout/ThemableLayout.java

@@ -18,6 +18,7 @@
 import java.util.Set;
 
 import com.vaadin.flow.component.HasElement;
+import com.vaadin.flow.component.Unit;
 import com.vaadin.flow.dom.Style;
 import com.vaadin.flow.dom.ThemeList;
 
@@ -93,16 +94,63 @@ default boolean isPadding() {
      *            it if {@code false}
      */
     default void setSpacing(boolean spacing) {
+        if (!spacing) {
+            getElement().getStyle().remove("gap");
+        }
         getThemeList().set("spacing", spacing);
     }
 
     /**
-     * Shows if {@code spacing} theme setting is applied to the component.
+     * Shows if {@code spacing} setting is applied to the component, either by
+     * setting the {@code spacing} theme or by setting the {@code gap} style.
      *
      * @return {@code true} if theme setting is applied, {@code false} otherwise
      */
     default boolean isSpacing() {
-        return getThemeList().contains("spacing");
+        return getThemeList().contains("spacing")
+                || getElement().getStyle().has("gap");
+    }
+
+    /**
+     * Sets the spacing between the components inside the layout.
+     *
+     * @param spacing
+     *            the spacing between the components. The value must be a valid
+     *            CSS length, i.e. must provide a unit (e.g. "1px", "1rem",
+     *            "1%") for values other than 0.
+     */
+    default void setSpacing(String spacing) {
+        getElement().getStyle().set("gap", spacing);
+    }
+
+    /**
+     * Sets the spacing between the components inside the layout.
+     *
+     * @param spacing
+     *            the spacing between the components
+     * @param unit
+     *            the unit of the spacing value
+     */
+    default void setSpacing(float spacing, Unit unit) {
+        if (spacing < 0) {
+            setSpacing(false);
+        }
+        setSpacing(spacing + unit.toString());
+    }
+
+    /**
+     * Gets the spacing between the components inside the layout.
+     *
+     * <p>
+     * The value returned is the value set by {@link #setSpacing(String)} or
+     * {@link #setSpacing(float, Unit)}. If the spacing was set using
+     * {@link #setSpacing(boolean)}, this method will return {@code null}. On
+     * this case, use {@link #isSpacing()} instead.
+     *
+     * @return the spacing between the components
+     */
+    default String getSpacing() {
+        return getElement().getStyle().get("gap");
     }
 
     /**

vaadin-ordered-layout-flow-parent/vaadin-ordered-layout-flow/src/test/java/com/vaadin/flow/component/orderedlayout/tests/ThemableLayoutTest.java

@@ -15,7 +15,9 @@
  */
 package com.vaadin.flow.component.orderedlayout.tests;
 
+import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNull;
 import static org.junit.Assert.assertTrue;
 
 import java.util.function.Consumer;
@@ -24,6 +26,7 @@
 import org.junit.Before;
 import org.junit.Test;
 
+import com.vaadin.flow.component.Unit;
 import com.vaadin.flow.component.orderedlayout.ThemableLayout;
 import com.vaadin.flow.dom.Element;
 import com.vaadin.flow.dom.ElementFactory;
@@ -69,6 +72,51 @@ public void checkWrap() {
         checkThemeToggling("wrap", layout::isWrap, layout::setWrap);
     }
 
+    @Test
+    public void checkSpacingStringSetter() {
+        layout.setSpacing("20px");
+        assertTrue("Expected spacing to be applied after setting it",
+                layout.isSpacing());
+        assertEquals("Expected spacing to be '20px'", "20px",
+                layout.getSpacing());
+    }
+
+    @Test
+    public void checkSpacingUnitSetter() {
+        layout.setSpacing(2, Unit.REM);
+        assertTrue("Expected spacing to be applied after setting it",
+                layout.isSpacing());
+        assertEquals("Expected spacing to be '2.0rem'", "2.0rem",
+                layout.getSpacing());
+    }
+
+    @Test
+    public void checkIsSpacing() {
+        layout.setSpacing("20px");
+        assertTrue("Expected spacing to be applied after setting it",
+                layout.isSpacing());
+        layout.setSpacing(false);
+        assertFalse("Expected no spacing applied after removing it",
+                layout.isSpacing());
+        layout.setSpacing(true);
+        assertTrue("Expected spacing to be applied after setting it",
+                layout.isSpacing());
+        layout.setSpacing(false);
+        assertFalse("Expected no spacing applied after removing it",
+                layout.isSpacing());
+    }
+
+    @Test
+    public void removeSpacing_gapIsRemoved() {
+        layout.setSpacing("20px");
+        layout.setSpacing(false);
+        assertFalse("Expected spacing to be removed after setting it to false",
+                layout.isSpacing());
+        assertNull("Expected spacing to be null", layout.getSpacing());
+        assertNull("Expected gap to be null",
+                layout.getElement().getStyle().get("gap"));
+    }
+
     private void checkThemeToggling(String themeName,
             Supplier<Boolean> themeGetter, Consumer<Boolean> themeSetter) {
         assertFalse(String.format(