Add theme variants documentation (#216)

documentation/src/main/html/ThemeVariants.html

@@ -0,0 +1,3 @@
+tutorial::theme/using-component-themes.asciidoc
+<vaadin-button theme="contrast primary">Themed button</vaadin-button>
+

documentation/src/main/java/com/vaadin/flow/tutorial/theme/ReadyMadeThemes.java

@@ -1,6 +1,9 @@
 package com.vaadin.flow.tutorial.theme;
 
+import java.util.Arrays;
+
 import com.vaadin.flow.component.button.Button;
+import com.vaadin.flow.component.button.ButtonVariant;
 import com.vaadin.flow.component.html.Div;
 import com.vaadin.flow.router.Route;
 import com.vaadin.flow.router.RouterLayout;
@@ -54,6 +57,22 @@ public class MyTheme extends Lumo {
 
     public void buttonVariant() {
         Button button = new Button("Themed button");
-        button.getElement().setAttribute("theme", "contrast primary");
+        button.addThemeVariants(ButtonVariant.LUMO_PRIMARY,
+                ButtonVariant.LUMO_CONTRAST);
+    }
+
+    public void buttonVariant2() {
+        Button button = new Button("Themed button");
+        button.getThemeNames().addAll(Arrays.asList("contrast", "primary"));
+    }
+
+    public void buttonVariant3() {
+        Button button = new Button("Themed button");
+        String themeAttributeName = "theme";
+        String oldValue = button.getElement().getAttribute(themeAttributeName);
+        String variantsToAdd = "contrast primary";
+        button.getElement().setAttribute(themeAttributeName,
+                oldValue == null || oldValue.isEmpty() ? variantsToAdd
+                        : ' ' + variantsToAdd);
     }
 }

documentation/theme/using-component-themes.asciidoc

@@ -66,16 +66,20 @@ If the Theme annotation is not on a `@Route` Component or a top `RouterLayout` a
 
 == Theme variants
 
-You can use a Theme variant by defining it on the `@Theme` annotation:
-[source,java]
+A variant is a special string value that can be placed in the `theme` attribute value of any html element.
+When the corresponding theme enabled, those values change the components' visual appearance.
+
+Multiple variants can be applied to the element, if specified separated by whitespace:
+
+.Html representation of the variants
+[source,html]
 ----
-@Route(value = "")
-@Theme(value = MyTheme.class, variant = "large")
-public class LargeThemedApplication extends Div {
-}
+<vaadin-button theme="contrast primary">Themed button</vaadin-button>
 ----
 
-Variants are like "skins" for the theme - it uses the same files for the theme, but sets special selectors in the body to make it appear different.
+There are two types of variants: theme variants, specific for the current theme and working globally
+and component variants, specific to the current component and theme.
+Different themes and different components may have different sets of variants (or none).
 
 == Available Themes and Customizations
 
@@ -94,7 +98,18 @@ See link:https://github.com/vaadin/vaadin-themable-mixin/wiki[vaadin-themable-mi
 
 === Using Vaadin theme variants
 
-Lumo and Material themes come with two variants: light (the default) and dark. You can use the dark variant by using:
+In Flow, you can set a theme variant by defining it on the `@Theme` annotation:
+[source,java]
+----
+@Route(value = "")
+@Theme(value = MyTheme.class, variant = "large")
+public class LargeThemedApplication extends Div {
+}
+----
+
+Lumo and Material themes come with two variants: light (the default) and dark.
+
+By default, no theme variants are used. You can use the dark variant by using:
 
 .Setting the dark variant for Lumo
 [source,java]
@@ -105,6 +120,7 @@ public class DarkApplication extends Div {
 }
 ----
 and the same can be done for Material theme:
+
 .Setting the dark variant for Material
 [source,java]
 ----
@@ -116,14 +132,61 @@ public class DarkMaterialApplication extends Div {
 
 Individual components have also variants available.
 Component variants are applied by using the element API to set the variant as the `theme` attribute.
-For example, to create a Button with https://vaadin.com/components/vaadin-button/html-examples/button-lumo-theme-demos[increased legibility], you can use:
+For example, to create a Button with https://vaadin.com/components/vaadin-button/html-examples/button-lumo-theme-demos[increased legibility],
+you can use `addThemeVariants` method:
+
+.Adding theme variants for the component
+[source,java]
+----
+Button button = new Button("Themed button");
+        button.addThemeVariants(ButtonVariant.LUMO_PRIMARY,
+                ButtonVariant.LUMO_CONTRAST);
+----
+
+For each component, there is a predefined set of variants that you can use.
+Those variants are theme-specific and different for each of the component (some may have none).
+For each component that has variants, Flow provides an api similar to the one in the example above to use it.
+
+When added, variants are converted to their html values
+(for a button variant, `ButtonVariant.LUMO_PRIMARY.getVariantName()` is used)
+and those representations are added to the `theme` attribute values.
+
+If the component implements `HasTheme` interface (which is true for every component that has `addThemeVariants` method),
+then the following API can be used:
+
+.Adding theme values for the component that implements `HasTheme` interface
+[source,java]
+----
+Button button = new Button("Themed button");
+button.getThemeNames().addAll(Arrays.asList("contrast", "primary"));
+----
 
-.Setting a theme variant for a component
+If you want more flexibility (which may come in handy when adding non-standard theme variants to the component),
+you can manipulate the value of the `theme` attribute directly:
+
+.Adding variants to the 'theme' attribute of the component
 [source,java]
 ----
 Button button = new Button("Themed button");
-button.getElement().setAttribute("theme", "contrast primary");
+        String themeAttributeName = "theme";
+        String oldValue = button.getElement().getAttribute(themeAttributeName);
+        String variantsToAdd = "contrast primary";
+        button.getElement().setAttribute(themeAttributeName,
+                oldValue == null || oldValue.isEmpty() ? variantsToAdd
+                        : ' ' + variantsToAdd);
 ----
 
-The `contrast primary` String in this case are theme variants for the Button component. For looking up all available component variants,
-https://vaadin.com/components/browse[see the component HTML examples] and look under the _Lumo Theme_ tab for examples of the variants.
+Each of the three examples above do the very same thing in the end:
+add `contrast` and `primary` Lumo Theme variants to the `theme` attribute value of the button component.
+
+For looking up all available component variants, https://vaadin.com/components/browse[see the component HTML examples]
+and look under the _Lumo Theme_ tab for examples of the variants.
+
+[NOTE]
+Theme variants for components work only when the corresponding theme is enabled.
+If a different theme or no theme is enabled, then with variants present in `theme` attribute of the corresponding component,
+no actual changes for the component's look and feel are made.
+
+As was mentioned earlier, by default, if no explicit theme configuration is done and `vaadin-lumo-theme`
+dependency is present in the classpath, LumoTheme is used.
+