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, 485 insertions, 94 deletions

diff --git a/WebContent/VAADIN/themes/valo/shared/_variables.scss b/WebContent/VAADIN/themes/valo/shared/_variables.scss
index 7dd3827298..4634a71fea 100644
--- a/WebContent/VAADIN/themes/valo/shared/_variables.scss
+++ b/WebContent/VAADIN/themes/valo/shared/_variables.scss
@@ -1,88 +1,459 @@
 // Color functions are used to calculate default font color
 @import "../util/color";
 
-
-
-// A static text that is shown while the application JavaScript is loaded and started
-$v-app-loading-text               : ""                                          !default;
-
-
-// Base line height used for all widgets
-$v-line-height                    : 1.55                                        !default;
-
-
-$v-background-color               : hsl(210, 0%, 98%)                           !default;
-$v-app-background-color           : $v-background-color                         !default;
-
-$v-font-size                      : 16px                                        !default; // Should be specified in pixels
-$v-font-weight                    : 300                                         !default; // Must be specified as a numeric value (i.e. not 'normal' or 'bold')
-$v-font-color                     : valo-font-color($v-app-background-color)    !default;
-$v-font-family                    : "Open Sans", sans-serif                     !default;
-
-$v-caption-font-size              : round($v-font-size * 0.9)                   !default; // Should be a pixel value
-$v-caption-font-weight            : max(400, $v-font-weight)                    !default;
-
-$v-unit-size                      : round(2.3 * $v-font-size)                   !default; // Must be specified in pixels (suitable range 18-50)
-
-$v-layout-margin-top              : round($v-unit-size)                         !default;
-$v-layout-margin-right            : round($v-unit-size)                         !default;
-$v-layout-margin-bottom           : round($v-unit-size)                         !default;
-$v-layout-margin-left             : round($v-unit-size)                         !default;
-
-$v-layout-spacing-vertical        : round($v-unit-size/3)                       !default;
-$v-layout-spacing-horizontal      : round($v-unit-size/3)                       !default;
-
-$v-border                         : 1px solid (v-shade 0.7)                     !default; // Size must be specified in pixels
-$v-border-radius                  : 4px                                         !default; // Must be specified in pixels
-
-$v-gradient                       : v-linear 8%                                 !default;
-
-$v-bevel                          : inset 0 1px 0 v-tint, inset 0 -1px 0 v-shade !default;
-$v-bevel-depth                    : 30%                                         !default;
-
-$v-shadow                         : 0 2px 3px v-shade                           !default;
-$v-shadow-opacity                 : 5%                                          !default;
-
-$v-focus-color                    : valo-focus-color()                          !default;
-$v-focus-style                    : 0 0 0 2px rgba($v-focus-color, .5)          !default;
-
-$v-animations-enabled             : true                                        !default;
-$v-hover-styles-enabled           : true                                        !default;
-
-$v-disabled-opacity               : 0.5                                         !default;
-
-$v-selection-color                : $v-focus-color                              !default;
-
-$v-default-field-width            : $v-unit-size * 5                            !default;
-
-$v-error-indicator-color          : #ed473b                                     !default;
-$v-required-field-indicator-color : $v-error-indicator-color                    !default;
-$v-friendly-color                 : #2c9720                                     !default;
-
-
-$v-scaling-factor--tiny           : 0.75                                        !default;
-$v-scaling-factor--small          : 0.85                                        !default;
-$v-scaling-factor--large          : 1.2                                         !default;
-$v-scaling-factor--huge           : 1.6                                         !default;
-
-$v-unit-size--tiny                : round($v-unit-size * $v-scaling-factor--tiny)  !default;
-$v-unit-size--small               : round($v-unit-size * $v-scaling-factor--small) !default;
-$v-unit-size--large               : round($v-unit-size * $v-scaling-factor--large) !default;
-$v-unit-size--huge                : round($v-unit-size * $v-scaling-factor--huge)  !default;
-
-$v-font-size--tiny                : ceil($v-font-size * $v-scaling-factor--tiny)  !default;
-$v-font-size--small               : ceil($v-font-size * $v-scaling-factor--small) !default;
-$v-font-size--large               : ceil($v-font-size * $v-scaling-factor--large) !default;
-$v-font-size--huge                : ceil($v-font-size * $v-scaling-factor--huge)  !default;
-
-
-
-// List of components to include in the theme compilation. The list can be modified to make
-// the compiled theme smaller by removing unused components from the list.
-//
-// @usage
-// // Remove the Calendar component styles from the output
-// $v-included-components: remove($v-included-components, calendar);
+/**
+ * A static text that is shown under the loading spinned while the client-side
+ * engine is being loaded and started. The text must be given in quotes. The
+ * text can not be localized currently.
+ *
+ * @type string, quoted
+ */
+$v-app-loading-text: "" !default;
+
+/**
+ * Base line height for all widgets. It must be given a unitless number.
+ *
+ * @group typography
+ * @type number
+ */
+$v-line-height: 1.55 !default;
+
+/**
+ * Base font size for the theme. The font size defines the overall sizing of
+ * UI components by default. Must be specified in pixels.
+ *
+ * @group typography
+ * @type size (px)
+ */
+$v-font-size: 16px !default;
+
+/**
+ * Base font weight for plain text.
+ * Must be specified as a numeric value: 100, 200, 300 (light), 400 (regular),
+ * 500, 600, 700 (bold), 800 or 900.
+ *
+ * @group typography
+ * @type number
+ */
+$v-font-weight: 300 !default;
+
+/**
+ * Base font family for the theme. Can be any valid CSS font stack.
+ *
+ * @group typography
+ * @type list
+ */
+$v-font-family: "Open Sans", sans-serif !default;
+
+/**
+ * Font size for generic component captions. Can be any valid CSS font-size. A
+ * round pixel value is recommended.
+ *
+ * @group typography
+ * @type number
+ */
+$v-caption-font-size: round($v-font-size * 0.9) !default;
+
+/**
+ * Font weight for generic component captions. Can be any valid CSS font-weight.
+ *
+ * @group typography
+ * @type number | identifier
+ */
+$v-caption-font-weight: max(400, $v-font-weight) !default;
+
+/**
+ * Border specification for the components that have a border. The border width
+ * must be specified in pixels. For the border color, you can specify any CSS color
+ * or one of the v-tint, v-shade, and v-tone keywords.
+ *
+ * @group style
+ * @type list
+ */
+$v-border: 1px solid (v-shade 0.7) !default;
+
+/**
+ * Corner radius for components that have a border. The measure must be specified as a
+ * single pixel value (i.e. not as a list of values for each corner).
+ *
+ * @group style
+ * @type size (px)
+ */
+$v-border-radius: 4px !default;
+
+/**
+ * Color gradient style for components that have a gradient. The gradient style may use
+ * the following keywords: v-linear and v-linear-reverse. The opacity must be given
+ * as percentage between 0% and 100%.
+ * 
+ * #### Gradient styles
+ * 
+ *  - __v-linear__ - The start of the gradient is a lighter shade of the base color and the end is a darker shade of the base color. A basic linear gradient.
+ *  - __v-linear-reverse__ - Same as v-linear, but the color stops are reversed (darker at the start and lighter at the end)
+ *
+ * @group style
+ * @type list
+ */
+$v-gradient: v-linear 8% !default;
+
+/**
+ * Inset shadow style to define how some components are "raised" from the background.
+ * The value follows the syntax of CSS box-shadow, and should be a list of insets.
+ * For the bevel color, you can specify any CSS color or one of the v-tint, v-shade,
+ * and v-tone keywords.
+ *
+ * @group style
+ * @type list
+ */
+$v-bevel: inset 0 1px 0 v-tint, inset 0 -1px 0 v-shade !default;
+
+/**
+ * Specifies the "depth" of the bevel shadow, as applied to one of the color keywords for
+ * the bevel style. The actual amount of tint, shade, or tone is computed from the depth.
+ *
+ * @group style
+ * @type number (pct)
+ */
+$v-bevel-depth: 30% !default;
+
+/**
+ * Default shadow style for all components. As with $v-bevel, the value follows the syntax
+ * of CSS box-shadow, but without the inset. For the shadow color, you can specify any CSS
+ * color or one of the v-tint or v-shade keywords.
+ *
+ * @group style
+ * @type list
+ */
+$v-shadow: 0 2px 3px v-shade !default;
+
+/**
+ * Specifies the opacity of the shadow, as applied to one of the color keywords for the
+ * shadow style. The actual amount of tint or shade is computed from the depth.
+ *
+ * @group style
+ * @type number (pct)
+ */
+$v-shadow-opacity: 5% !default;
+
+/**
+ * The background color is the main control parameter for the Valo theme and
+ * it is  used for computing all other colors in the theme. If the color is dark
+ * (has low luminance),  * light foreground colors that give high contrast
+ * with the background are automatically used.
+ *
+ * Can be any valid CSS color.
+ *
+ * @group color
+ * @type color
+ */
+$v-background-color: hsl(210, 0%, 98%) !default;
+
+/**
+ * Background color of the UI's root element. You can specify the color in
+ * any way allowed in CSS. Used as the base for other default colors, such
+ * as panel and window content areas.
+ *
+ * Can be any valid CSS color.
+ *
+ * @group color
+ * @type color
+ */
+$v-app-background-color: $v-background-color !default;
+
+/**
+ * Base font color for the theme. Can be any valid CSS color.
+ *
+ * @group color
+ * @type color
+ */
+$v-font-color: valo-font-color($v-app-background-color) !default;
+
+/**
+ * Color for the field focus indicator. The valo-focus-color() function computes a
+ * high-contrast color from the context, which is usually the background color. The color
+ * can be any CSS color.
+ *
+ * @group color
+ * @type color
+ */
+$v-focus-color: valo-focus-color() !default;
+
+/**
+ * Box-shadow specification for the field focus indicator. The space-separated values
+ * are the horizontal shadow position in pixels, vertical shadow position in pixels,
+ * blur distance in pixels, spread distance in pixels, and the color. The color can be
+ * any CSS color. You can only specify the color, in which case defaults for the position
+ * are used. rgba() or hsla() can be used to enable transparency.
+ *
+ * @group style
+ * @type list | color
+ */
+$v-focus-style: 0 0 0 2px rgba($v-focus-color, .5) !default;
+
+/**
+ * Opacity of disabled components, from 0 to 1. Not all components have reduced opacity when disabled, such as Labels.
+ *
+ * @group style
+ * @type number
+ */
+$v-disabled-opacity: 0.5 !default;
+
+/**
+ * Color for indicating selection in selection components.
+ *
+ * @group color
+ * @type color
+ */
+$v-selection-color: $v-focus-color !default;
+
+/**
+ * Color of the component error indicator and other error indications, such as the
+ * error style notification.
+ *
+ * @group color
+ * @type color
+ */
+$v-error-indicator-color: #ed473b !default;
+
+/**
+ * Color of the required indicator in field components.
+ *
+ * @group color
+ * @type color
+ */
+$v-required-field-indicator-color: $v-error-indicator-color !default;
+
+/**
+ * Color used for success states and to indicate safe actions (i.e. actions that
+ * will not cause any data loss).
+ *
+ * @group color
+ * @type color
+ */
+$v-friendly-color: #2c9720 !default;
+
+/**
+ * Color specifications for $v-border, $v-bevel, and $v-shadow may use, in addition to CSS colors, the following keywords:
+ *
+ *  - __v-tint__ - Lighter than the background color
+ *  - __v-shade__ - Darker than the background color
+ *  - __v-tone__ - Adaptive color specification: darker on light background and lighter on dark background. Not usable in $v-shadow.
+ *
+ *
+ *  These keywords can be further adjusted by combining them with a strength multiplier, specified in parenthesis.
+ *
+ *  Examples:
+ *
+ *      (v-tint 2)
+ *      (v-shade 0.6)
+ *      (v-tone 1.1)
+ *
+ * @group color
+ */
+$v-color-keywords: v-tint, v-shade, v-tone;
+
+/**
+ * This is the base size for various layout measures. It is directly used in some
+ * measures, such as button height and layout margins, while other measures are
+ * derived from it. The value must be specified in pixels, with a suitable range
+ * of 18-50.
+ *
+ * @group layout
+ * @type size (px)
+ */
+$v-unit-size: round(2.3 * $v-font-size) !default;
+
+/**
+ * Scaling factor for tiny sizes. Must be a unitless number.
+ *
+ * @group layout
+ * @type number
+ */
+$v-scaling-factor--tiny: 0.75 !default;
+
+/**
+ * Scaling factor for small sizes. Must be a unitless number.
+ *
+ * @group layout
+ * @type number
+ */
+$v-scaling-factor--small: 0.85 !default;
+
+/**
+ * Scaling factor for large sizes. Must be a unitless number.
+ *
+ * @group layout
+ * @type number
+ */
+$v-scaling-factor--large: 1.2 !default;
+
+/**
+ * Scaling factor for huge sizes. Must be a unitless number.
+ *
+ * @group layout
+ * @type number
+ */
+$v-scaling-factor--huge: 1.6 !default;
+
+/**
+ * Unit size for tiny components. Must be a pixel value.
+ *
+ * @group layout
+ * @type size (px)
+ */
+$v-unit-size--tiny: round($v-unit-size * $v-scaling-factor--tiny) !default;
+
+/**
+ * Unit size for small components. Must be a pixel value.
+ *
+ * @group layout
+ * @type size (px)
+ */
+$v-unit-size--small: round($v-unit-size * $v-scaling-factor--small) !default;
+
+/**
+ * Unit size for large components. Must be a pixel value.
+ *
+ * @group layout
+ * @type size (px)
+ */
+$v-unit-size--large: round($v-unit-size * $v-scaling-factor--large) !default;
+
+/**
+ * Unit size for huge components. Must be a pixel value.
+ *
+ * @group layout
+ * @type size (px)
+ */
+$v-unit-size--huge: round($v-unit-size * $v-scaling-factor--huge) !default;
+
+/**
+ * The top margin size for all built-in layout components, when the margin is
+ * enabled with setMargin(). Can be any valid CSS size.
+ *
+ * @group layout
+ * @type size
+ */
+$v-layout-margin-top: round($v-unit-size) !default;
+
+/**
+ * The right margin size for all built-in layout components, when the margin is
+ * enabled with setMargin(). Can be any valid CSS size.
+ *
+ * @group layout
+ * @type size
+ */
+$v-layout-margin-right: round($v-unit-size) !default;
+
+/**
+ * The bottom margin size for all built-in layout components, when the margin is
+ * enabled with setMargin(). Can be any valid CSS size.
+ *
+ * @group layout
+ * @type size
+ */
+$v-layout-margin-bottom: round($v-unit-size) !default;
+
+/**
+ * The left margin size for all built-in layout components, when the margin is
+ * enabled with setMargin(). Can be any valid CSS size.
+ *
+ * @group layout
+ * @type size
+ */
+$v-layout-margin-left: round($v-unit-size) !default;
+
+/**
+ * Amount of vertical space when spacing is enabled for a layout with setSpacing().
+ * Can be any valid CSS size.
+ *
+ * @group layout
+ * @type size
+ */
+$v-layout-spacing-vertical: round($v-unit-size/3) !default;
+
+/**
+ * Amount of horizontal space when spacing is enabled for a layout with setSpacing().
+ * Can be any valid CSS size.
+ *
+ * @group layout
+ * @type size
+ */
+$v-layout-spacing-horizontal: round($v-unit-size/3) !default;
+
+/**
+ * Tiny font size.
+ *
+ * @group typography
+ * @type size (px)
+ */
+$v-font-size--tiny: ceil($v-font-size * $v-scaling-factor--tiny) !default;
+
+/**
+ * Small font size.
+ *
+ * @group typography
+ * @type size (px)
+ */
+$v-font-size--small: ceil($v-font-size * $v-scaling-factor--small) !default;
+
+/**
+ * Large font size.
+ *
+ * @group typography
+ * @type size (px)
+ */
+$v-font-size--large: ceil($v-font-size * $v-scaling-factor--large) !default;
+
+/**
+ * Huge font size.
+ *
+ * @group typography
+ * @type size (px)
+ */
+$v-font-size--huge: ceil($v-font-size * $v-scaling-factor--huge) !default;
+
+/**
+ * Default width of certain field components, unless overridden with setWidth().
+ *
+ * @group layout
+ * @type size (px)
+ */
+$v-default-field-width: $v-unit-size * 5 !default;
+
+/**
+ * Specifies whether various CSS animations are used. Not all animations are disabled when
+ * set to false, such as the default loading indicator animations.
+ *
+ * @group optimization
+ * @type bool
+ */
+$v-animations-enabled: true !default;
+
+/**
+ * Specifies whether various :hover styles are used for indicating that mouse pointer
+ * hovers over an element.
+ *
+ * @group optimization
+ * @type bool
+ */
+$v-hover-styles-enabled: true !default;
+
+/**
+ * List of components to include in the theme compilation. The list can be modified to make
+ * the compiled theme smaller by removing unused components from the list.
+ *
+ * @group optimization
+ * @type list
+ *
+ * @example scss
+ * // Remove the Calendar component styles from the output (must be declared after importing Valo)
+ * $v-included-components: remove($v-included-components, calendar);
+ *
+ * @example scss
+ * // Only include the Label, Button and Vertical and Horizontal layouts in the compilation
+ * $v-included-components: label, button, orderedlayout;
+ */
 $v-included-components:
     absolutelayout,
     accordion,
@@ -125,23 +496,43 @@ $v-included-components:
     window,
     valo-menu !default;
 
-
+/**
+ * List of components whose additional styles should be included in the compilation.
+ *
+ * @group optimization
+ * @type list
+ */
 $v-included-additional-styles: $v-included-components !default;
 
-
-// Checks if a given component is included in the compilation. Used by the collection mixins that
-// include all components, like valo-components and valo-components.
-// @param     $component-name {String} the name of the component to check
-// @param     $is-included {list} (Optional) the list of components which is checked
-// @return    {Boolean} true if the component is included in the compilation, false if not
+/**
+ * Checks if a given component is included in the compilation. Used by the collection mixins that
+ * include all components (i.e. valo-components).
+ *
+ * @requires $v-included-components
+ *
+ * @example scss
+ *  @if v-is-included(button) {
+ *    // The Button component is included in the compilation
+ *  }
+ *
+ * @param {string} $component-name - the name of the component to check
+ * @param {list} $is-included ($v-included-components) - the list of components which is checked
+ *
+ * @return {bool} true if the component is included in the compilation, false if not
+ *
+ * @group optimization
+ */
 @function v-is-included ($component-name, $is-included: $v-included-components) {
   @return contains($is-included, $component-name);
 }
 
 
-
-// A flag to note whether relative URL paths are relative to the currently parsed SCSS file or to the compilation root file.
-// The Vaadin compiler parses URL paths differently than the regular Sass compiler (i.e. Vaadin modifies relative url paths).
-// This boolean is used to flag which compiler is used, so that paths are correct for different resources.
-// false == Ruby, true == Vaadin
+/**
+ * A flag to note whether relative URL paths are relative to the currently parsed SCSS file or to the compilation root file.
+ * The Vaadin compiler parses URL paths differently than the regular Sass compiler (i.e. Vaadin modifies relative url paths).
+ * This boolean is used to flag which compiler is used, so that paths are correct for different resources.
+ * false == Ruby, true == Vaadin
+ *
+ * @type bool
+ */
 $v-relative-paths: true !default;