First batch of Valo Sass API documentation, plus bug fixes

Also updates the test to always scroll the left panel to the top after
opening a section.

Change-Id: Icdb42795b8ec347b91694c162898f41aa8d80152

1 files changed, 55 insertions, 3 deletions

diff --git a/WebContent/VAADIN/themes/valo/util/_util.scss b/WebContent/VAADIN/themes/valo/util/_util.scss
index 1f983c0dad..585504600d 100644
--- a/WebContent/VAADIN/themes/valo/util/_util.scss
+++ b/WebContent/VAADIN/themes/valo/util/_util.scss
@@ -1,4 +1,12 @@
-// Align element vertically inside
+/**
+ * Ouput selectors and properties to vertically center elements inside their parent.
+ * 
+ * @param {string} $to-align (()) - The selector to match the elements which you wish to align vertically. The targeted elements should be inline or inline-block elements.
+ * @param {string} $align (middle) - The vertical-align value, e.g. top, middle, bottom
+ * @param {string} $pseudo-element (after) - Which pseudo element to use for the vertical align guide
+ * 
+ * @group util
+ */
 @mixin valo-vertical-align-guide ($to-align: (), $align: middle, $pseudo-element: after) {
   &:#{$pseudo-element} {
     content: "";
@@ -18,7 +26,11 @@
 }
 
 
-
+/**
+ * Indicate that an element is clickable/tappable
+ * 
+ * @group util
+ */
 @mixin valo-tappable {
   -webkit-tap-highlight-color: rgba(0,0,0,0);
   -webkit-touch-callout: none;
@@ -26,13 +38,53 @@
 }
 
 
-
+/**
+ * Output Vaadin Responsive extension specific width-range declaration.
+ * 
+ * @param {size} $min (0) - The lower bound for the width-range
+ * @param {size} $max (null) - The upper bound for the width-range
+ * 
+ * @group util
+ * 
+ * @example scss
+ * .v-ui {
+ *   font-size: 18px;
+ *   
+ *   // Make the font-size smaller for 481px-768px wide UIs
+ *   @include width-range(481px, 768px) {
+ *     font-size: 16px;
+ *   }
+ *   
+ *   // Make it even smaller for UIs narrower than 480px
+ *   @include width-range($max: 480px) {
+ *     font-size: 14px;
+ *   }
+ * }
+ */
 @mixin width-range($min: 0, $max: null) {
   &[width-range~="#{$min}-#{$max}"] {
     @content;
   }
 }
 
+/**
+ * Output Vaadin Responsive extension specific height-range declaration.
+ * 
+ * @param {size} $min (0) - The lower bound for the height-range
+ * @param {size} $max (null) - The upper bound for the height-range
+ * 
+ * @group util
+ * 
+ * @example scss
+ * .v-csslayout {
+ *   color: red;
+ *   
+ *   // Make the text color blue when the layout height is between 100px-300px
+ *   @include height-range(100px, 300px) {
+ *     color: blue;
+ *   }
+ * }
+ */
 @mixin height-range($min: 0, $max: null) {
   &[height-range~="#{$min}-#{$max}"] {
     @content;