igniteui-theming 1.1.4 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "igniteui-theming",
-  "version": "1.1.4",
+  "version": "1.2.0",
   "description": "A set of Sass variables, mixins, and functions for generating palettes, typography, and elevations used by Ignite UI components.",
   "main": "index.js",
   "scripts": {

package/sass/bem/_index.scss

@@ -138,7 +138,7 @@ $bem--sep-mod-val: if(meta.variable-exists(bem--sep-mod-val), $bem--sep-mod-val,
 /// @example scss Include a block and an element
 ///   @include bem-selector(block, $e:elem); // outputs .block__elem
 /// @example scss Include block, element, and element modifier
-///   @include bem-selector(block, $e:(elem,emod); // outputs .block__elem-emod
+///   @include bem-selector(block, $e:(elem, $mod); // outputs .block__elem-emod
 /// @example scss Include block and block modifier
 ///   @include bem-selector(block, $m:mod) // outputs .block--mod
 /// @example scss Include block and modifier value
@@ -191,8 +191,14 @@ $bem--sep-mod-val: if(meta.variable-exists(bem--sep-mod-val), $bem--sep-mod-val,
 
 /// Simply unrolls into a class-selector. The main purpose of using this mixin
 /// is to clearly denote the start of a BEM block.
-/// @access public
+/// @access public scss
 /// @param {String} $block - The block name.
+/// @example
+///   @include bem-block(block) {
+///      background: green;
+///   }
+///   // Return
+///   .block { background: green; }
 @mixin bem-block($block) {
     @at-root {
         #{bem-selector($block)} {
@@ -210,6 +216,14 @@ $bem--sep-mod-val: if(meta.variable-exists(bem--sep-mod-val), $bem--sep-mod-val,
 /// @param {String} $elem - The sub-element name.
 /// @param {String} $m - The modifier name.
 /// @param {String} $mod - An alias of `$m`.
+/// @example scss
+///   @include bem-block(block) {
+///      @include bem-elem(element) {
+///        background: blue;
+///      }
+///   }
+///   // Return
+///   .block__element { background: blue; }
 @mixin bem-elem($elem, $m: null, $mod: null, $mods: null) {
     $this: bem--selector-to-string(&);
     $block: bem--extract-block($this);
@@ -272,6 +286,14 @@ $bem--sep-mod-val: if(meta.variable-exists(bem--sep-mod-val), $bem--sep-mod-val,
 /// that should mean isn't clear.
 /// @access public
 /// @param {String} $mod - The modifier name.
+/// @example scss
+///   @include bem-block(block) {
+///      @include bem-mod(modifier) {
+///        background: red;
+///      }
+///   }
+///   // Return
+///   .block--modifier { background: red; }
 @mixin bem-mod($mod) {
     $skip: false;
     $this: bem--selector-to-string(&);
@@ -300,6 +322,18 @@ $bem--sep-mod-val: if(meta.variable-exists(bem--sep-mod-val), $bem--sep-mod-val,
 /// or block element when two or more modifiers are applied in tandem
 /// @access public
 /// @param {List} $mods - A list of modifiers
+/// @example scss
+///   @include bem-block(block) {
+///      @include bem-mods(error, warn) {
+///        position: absolute;
+///      }
+///   }
+///   // Return
+///   .block--error,
+///   .block--warn {
+///       position: absolute;
+///    }
+///
 @mixin bem-mods($mods...) {
     $this: bem--selector-to-string(&);
     $mod-classes: ();

package/sass/color/_functions.scss

@@ -15,6 +15,10 @@ $_enhanced-accessibility: false;
 /// @access public
 /// @group color
 /// @param {Boolean} $enhanced-accessibility [null] - Enables features like color blind palettes.
+/// @example scss
+///   .enhanced-accessibility {
+///      @include configure-colors(true);
+///    }
 @mixin configure-colors($enhanced-accessibility: null) {
     @if $enhanced-accessibility {
         $_enhanced-accessibility: $enhanced-accessibility !global;
@@ -28,22 +32,25 @@ $_enhanced-accessibility: false;
 /// @param {Color} $secondary - The secondary color used to generate the secondary color palette (required).
 /// @param {Color} $surface - The color used as a background in components, such as cards, sheets, and menus (required).
 /// @param {Color} $gray [null] - The color used for generating the grayscale palette (optional).
-/// @param {Color} $info [null] - The information color used throughout the application (optional).
-/// @param {Color} $success [null] - The success color used throughout the application (optional).
-/// @param {Color} $warn [null] - The warning color used throughout the application (optional).
-/// @param {Color} $error [null] - The error color used throughout the application (optional).
+/// @param {Color} $info [#1377d5] - The information color used throughout the application (optional).
+/// @param {Color} $success [#4eb862] - The success color used throughout the application (optional).
+/// @param {Color} $warn [#faa419] - The warning color used throughout the application (optional).
+/// @param {Color} $error [#ff134a] - The error color used throughout the application (optional).
 /// @param {String} $variant [null] - Used internally (optional).
 /// @requires {function} shades
 /// @returns {Map} - A map consisting of color shades for the passed base colors (primary, secondary, gray, etc).
+/// @example scss
+///   // $primary, $secondary, $surface are required parameters.
+///   $my-palette: palette($primary: #09f,$secondary #222, $surface: #fff);
 @function palette(
     $primary,
     $secondary,
     $surface,
     $gray: null,
-    $info: null,
-    $success: null,
-    $warn: null,
-    $error: null,
+    $info: #1377d5,
+    $success: #4eb862,
+    $warn: #faa419,
+    $error: #ff134a,
     $variant: null,
 ) {
     $color-shades: types.$IColorShades;
@@ -78,10 +85,12 @@ $_enhanced-accessibility: false;
 /// @param {String} $name - The name of the color.
 /// @param {Color} $color - The base color used to generate the palette.
 /// @param {List} $shades - The list of shades.
-/// @param {Color} $surface [null] - The surface color. Usefull when generating shades of gray (optional).
+/// @param {Color} $surface [null] - The surface color. Useful when generating shades of gray (optional).
 /// @requires {function} shade
 /// @requires {function} text-contrast
-/// @returns {Map} - A map consisting of hsla color shades and thier respective contrast colors.
+/// @returns {Map} - A map consisting of hsla color shades and their respective contrast colors.
+/// @example scss
+///   $special-color-shades: shades('accent', #09f, (50,100,200,300,400,500,600,700,800,900))
 @function shades(
     $name,
     $color,
@@ -111,7 +120,7 @@ $_enhanced-accessibility: false;
 /// @param {String} $name - The base color name (primary, secondary, etc.) to be used to generate a color variant.
 /// @param {Color} $color - The color value to be used to generate a color shade.
 /// @param {String | Number} $shade - The color shade variant.
-/// @param {Color} $surface [null] - The surface color. Usefull when generating a shade of gray (optional).
+/// @param {Color} $surface [null] - The surface color. Useful when generating a shade of gray (optional).
 /// @require {function} luminance
 /// @require {function} to-fixed
 /// @returns {Map} - A map containing a list of HSL values and a raw color value.
@@ -156,6 +165,9 @@ $_enhanced-accessibility: false;
     }
 }
 
+// $special-color-shades: shades('accent', #09f, (50,100,200,300,400,500,600,700,800,900));
+// @debug $special-color-shades;
+
 /// Retrieves a color from a color palette.
 /// @access public
 /// @group Palettes
@@ -164,6 +176,15 @@ $_enhanced-accessibility: false;
 /// @param {Number | String} $variant [500] - The target color shade from the color palette.
 /// @param {Number} $opacity [null] - Optional opacity to apply to the color shade.
 /// @returns {Color | String} - The raw color shade or CSS variable reference from the palette.
+/// @example scss
+///   // No palette
+///   .my-component-1 {
+///      background: color($color: 'primary', $variant: 200);
+///    }
+///    // Using certain palette and adding .5% opacity to the color variant
+///   .my-component-2 {
+///      background: color($my-palette, 'primary', 200, .5);
+///    }
 @function color($palette: null, $color: 'primary', $variant: 500, $opacity: null) {
     $c: map.get($palette or types.$IPalette, #{$color});
     $a: var(--ig-#{$color}-a);
@@ -190,7 +211,7 @@ $_enhanced-accessibility: false;
     @return rgba(map.get($c, $variant), $alpha: if($opacity, $opacity, 1));
 }
 
-/// Retrieves a contrast text color for a given color from a color palette.
+/// Retrieves a contrast text color for a given color variant from a color palette.
 /// @access public
 /// @group Palettes
 /// @param {Map} $palette [null] - The source palette map (optional).
@@ -198,6 +219,11 @@ $_enhanced-accessibility: false;
 /// @param {Number | String} $variant [500] - The target color shade from the color palette.
 /// @requires {function} color
 /// @returns {Color | String} - The raw contrast color shade or CSS variable from the palette.
+/// @example scss without passing a palette
+///   .my-component {
+///      background: color($color: 'primary', $variant: 200);
+///      color: contrast-color($color: 'primary', $variant: 200);
+///    }
 @function contrast-color($palette: null, $color: primary, $variant: 500) {
     @return color($palette, $color, #{$variant}-contrast);
 }
@@ -213,6 +239,11 @@ $_enhanced-accessibility: false;
 /// @returns {Color} - Returns either white, black, or the provided foreground
 /// color if it meets the required contrast level.
 /// @link https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html
+/// @example scss
+///   .my-component {
+///      background: #09f
+///      color: text-contrast(#09f)
+///    }
 @function text-contrast(
     $background,
     $foreground: white,
@@ -232,7 +263,7 @@ $_enhanced-accessibility: false;
     );
 
     @if not($level) {
-        @error "$contrast must be 'A', 'AA', or 'AAA'";
+        @error '$contrast must be \'A\', \'AA\', or \'AAA\'';
     }
 
     $candidates: ();
@@ -302,6 +333,8 @@ $_enhanced-accessibility: false;
 /// @param {Color} $foreground - The foreground color.
 /// @require {function} luminance
 /// @require {function} to-fixed
+/// @example scss
+///   contrast(#09f, #000);
 /// @returns {Number} - The contrast ratio between the background and foreground colors.
 @function contrast($background, $foreground) {
     $backLum: luminance($background) + .05;
@@ -315,6 +348,8 @@ $_enhanced-accessibility: false;
 /// @access public
 /// @group Color
 /// @param {Color} $color - The color to calculate luminance for.
+/// @example scss
+///   luminance(#09f);
 /// @returns {Number | String} - The calculated luminance of a given color
 @function luminance($color) {
     @if meta.type-of($color) == 'color' {

package/sass/elevations/_functions.scss

@@ -51,6 +51,12 @@ $factor: var(--ig-elevation-factor, 1);
 /// Sorts out a list of valid only box-shadows.
 /// @access public
 /// @param {List} $shadows - A list of shadow values.
+/// @example scss
+///   box-shadow((0 0 2px 3px black, 0 6px 9px orange));
+///   // Return
+///   box-shadow:
+///      0 0 calc(--ig-elevation-factor * 2px) calc(--ig-elevation-factor * 3px) black,
+///      0 calc(--ig-elevation-factor * 6px) calc(--ig-elevation-factor * 9px) orange;
 /// @return {List} - The transformed shadow list.
 /// @requires {function} _is-shadow
 /// @requires {function} _transform-shadow
@@ -82,6 +88,10 @@ $factor: var(--ig-elevation-factor, 1);
 /// Gets a CSS elevation variable by name.
 /// @access public
 /// @param {String} $name - The name of the shadow.
+/// @example scss
+///   .my-class {
+///     box-shadow: elevation(5);
+///   }
 /// @return {String} - The CSS elevation variable
 @function elevation($name) {
     @return var(--ig-elevation-#{$name});

package/sass/elevations/_mixins.scss

@@ -7,14 +7,15 @@
 /// Generates CSS variables for a given elevations map.
 /// @access public
 /// @param {Map} $elevations - The elevations map to use to generate CSS variables.
-///
 /// @example scss Generate CSS variables for elevations.
 ///   $elevations: (
 ///       small: box-shadow(0 .125rem .25rem rgba(0 0 0 / 75%)),
 ///       medium: box-shadow(0 .25rem .5rem rgba(0 0 0 / 85%)),
 ///       large: box-shadow(0 .75rem 1rem rgba(0 0 0 / 95%))
 ///   );
-///   @include elevations($elevations);
+///   :root {
+///       @include elevations($elevations);
+///   }
 /// @require {function} is-root
 @mixin elevations($elevations) {
     $scope: if(is-root(), ':root', '&');
@@ -29,6 +30,10 @@
 /// Includes box-shadow styles for an elevation by name
 /// @access public
 /// @param {String} $name - The name of the shadow.
+/// @example scss Include a box shadow by its name.
+///   .my-class {
+///     @include elevation(small);
+///   }
 @mixin elevation($name) {
     box-shadow: var(--ig-elevation-#{$name});
 }

package/sass/themes/_functions.scss

@@ -131,6 +131,8 @@
 /// @param {Number} $sm - The preferred value when the component's size is small.
 /// @param {Number} $md [$sm] - The preferred value when the component's size is medium.
 /// @param {Number} $lg [$md] - The preferred value when the component's size is large.
+/// @example
+///   --size: #{sizable(rem(40px), rem(64px), rem(88px))};
 /// @return {Function} - The evaluated value.
 @function sizable($sm, $md: $sm, $lg: $md) {
     @return max(
@@ -147,6 +149,10 @@
 /// @param {Number} $md [$sm] - The preferred value when the component's size is medium.
 /// @param {Number} $lg [$md] - The preferred value when the component's size is large.
 /// @param {Number} $dir [null] - The preferred direction - inline or block.
+/// @example
+///   .my-component {
+///     padding: pad(4px, 8px, 16px);
+///   }
 /// @return {Function} - The evaluated value.
 @function pad($sm, $md: $sm, $lg: $md, $dir: null) {
     $spacing: if($dir, --ig-spacing-#{$dir}, --ig-spacing);
@@ -164,6 +170,10 @@
 /// @param {Number} $sm - The preferred value when the component's size is small.
 /// @param {Number} $md [$sm] - The preferred value when the component's size is medium.
 /// @param {Number} $lg [$md] - The preferred value when the component's size is large.
+/// @example
+///   .my-component {
+///     padding: pad-inline(4px, 8px, 16px);
+///   }
 /// @return {Function} - The evaluated value.
 @function pad-inline($sm, $md: $sm, $lg: $md) {
     @return pad($sm, $md, $lg, $dir: inline);
@@ -175,6 +185,10 @@
 /// @param {Number} $sm - The preferred value when the component's size is small.
 /// @param {Number} $md [$sm] - The preferred value when the component's size is medium.
 /// @param {Number} $lg [$md] - The preferred value when the component's size is large.
+/// @example
+///   .my-component {
+///     padding: pad-block(4px, 8px, 16px);
+///   }
 /// @return {Function} - The evaluated value.
 @function pad-block($sm, $md: $sm, $lg: $md) {
     @return pad($sm, $md, $lg, $dir: block);

package/sass/themes/_mixins.scss

@@ -22,6 +22,7 @@ $ignored-keys: ('name', 'palette', 'variant', 'selector');
 /// @require {mixin} css-vars
 @mixin css-vars-from-theme($theme, $name, $ignored: $ignored-keys) {
     $themes: map.get($theme, 'themes');
+    $prefix: map.get($theme, 'prefix');
 
     // This is here only because the button theme consists of 4 nested themes.
     @if $themes and meta.type-of($themes) == 'map' {
@@ -31,8 +32,10 @@ $ignored-keys: ('name', 'palette', 'variant', 'selector');
     }
 
     @each $key, $value in map.remove($theme, $ignored...) {
-        @if meta.type-of($value) != 'map' {
-            --#{$key}: var(--#{$name}-#{$key}, #{$value});
+        $variable: if($prefix, #{$prefix}-#{$key}, #{$key});
+
+        @if meta.type-of($value) != 'map' and $key != 'prefix' {
+            --#{$variable}: var(--#{$name}-#{$key}, #{$value});
         }
     }
 }
@@ -43,6 +46,14 @@ $ignored-keys: ('name', 'palette', 'variant', 'selector');
 /// @param {map} $theme - The component theme to be used.
 /// @param {map} $scope [null] - The CSS variables scope to be used. (optional)
 /// @requires {mixin} css-vars-from-theme
+/// @example scss Convert grid theme colors to css variables
+///   $my-grid-theme grid-theme(
+///     $header-background: red,
+///     $content-background: #222
+///   );
+///   .my-grid {
+///     @include css-vars($my-grid-theme);
+///   }
 @mixin css-vars($theme, $scope: null) {
     $s: map.get($theme, 'selector');
     $n: map.get($theme, 'name');
@@ -69,6 +80,8 @@ $ignored-keys: ('name', 'palette', 'variant', 'selector');
 /// @param {Number} $radius - The preferred value.
 /// @param {Number} $min [rem(0)] - The minimum value.
 /// @param {Number} $max [$radius] - The maximum allowed value.
+/// @example scss
+///    @include border-radius(4px);
 @mixin border-radius($radius, $min: #{rem(0)}, $max: $radius) {
     border-radius: clamp(#{$min}, #{calc(var(--ig-radius-factor) * #{$radius})}, #{$max});
 }
@@ -92,6 +105,10 @@ $ignored-keys: ('name', 'palette', 'variant', 'selector');
 /// This won't work on display flex elements.
 /// @group utilities
 /// @access public
+/// @example scss
+///   .my-class {
+///     @include ellipsis();
+///   }
 @mixin ellipsis() {
     white-space: nowrap;
     text-overflow: ellipsis;
@@ -121,6 +138,10 @@ $ignored-keys: ('name', 'palette', 'variant', 'selector');
 /// Adds the required CSS properties so that the scope can react to size changes.
 /// @group themes
 /// @access public
+/// @example scss - Sample usage
+///   .my-component {
+///     @include sizable();
+///   }
 @mixin sizable() {
     --is-large: clamp(0, (var(--component-size, 1) + 1) - var(--ig-size-large, 3), 1);
     --is-medium:

package/sass/typography/_functions.scss

@@ -15,6 +15,10 @@ $browser-context: 16px;
 /// @access public
 /// @param {number|string} $pixels - The pixel value to be converted.
 /// @param {number|string} $context [$browser-context] - The base context to convert against.
+/// @example
+///   .my-component {
+///     margin: em(10px) em(5px);
+///   }
 /// @return {number} - Returns the pixels value converted to em.
 @function em($pixels, $context: $browser-context) {
     @if math.is-unitless($pixels) {
@@ -32,6 +36,10 @@ $browser-context: 16px;
 /// @access public
 /// @param {number|string} $pixels - The pixel value to be converted.
 /// @param {number|string} $context [$browser-context] - The base context to convert against.
+/// @example
+///   .my-component {
+///     margin: rem(10px) rem(5px);
+///   }
 /// @return {number} - Returns the pixels value converted to rem.
 @function rem($pixels, $context: $browser-context) {
     @if math.is-unitless($pixels) {
@@ -49,6 +57,10 @@ $browser-context: 16px;
 /// @access public
 /// @param {number|string} $num - The relative value to be converted.
 /// @param {number|string} $context [$browser-context] - The base context to convert against.
+/// @example
+///   .my-component {
+///     margin: px(3.23rem);
+///   }
 /// @return {number} - Returns the relative value converted to pixels.
 @function px($num, $context: $browser-context) {
     @if meta.type-of($num) == 'number' {
@@ -70,6 +82,19 @@ $browser-context: 16px;
 /// @param {Number} $margin-top [0] - The margin-top property of the type style.
 /// @param {Number} $margin-bottom [0] - The margin-bottom property of the type style.
 /// @requires $ITypeStyle
+/// @example
+///   $main_navigation: type-style(
+///      $font-size: rem(14px),
+///      $font-weight: 600,
+///      $letter-spacing: rem(.1px),
+///      $line-height: rem(14px),
+///      $text-transform: none,
+///   );
+///
+///   // Use the type-style() mixin to consume the new type style produced from the type-style() function.
+///   .main-nav {
+///     @include type-style($main_navigation);
+///   }
 /// @returns {Map} - A map of all defined type style properties.
 @function type-style($args...) {
     $keywords: meta.keywords($args);
@@ -111,6 +136,18 @@ $browser-context: 16px;
 /// @param {Map} $overline - A map containing type style properties as produces by the type-style function.
 /// @param {String} $_theme [null] - The theme related to this type scale. Internal use only.
 /// @requires $ITypeScale
+/// @example
+///   // First define type styles to use
+///   $my-body-1: type-style(
+///      $font-size: rem(14px),
+///   );
+///
+///   // Use the type style map to override one of the existing maps
+///   $type-scale: type-scale(
+///	    ...
+///	    $body-1: $my-body-1,
+///	    ...
+///   );
 /// @returns {Map} - A map of all defined type scales.
 @function type-scale($_theme: null, $args...) {
     $style_fn: meta.get-function('type-style');

package/sass/typography/_mixins.scss

@@ -108,6 +108,8 @@
 /// @requires {mixin} type-style-vars
 /// @requires {mixin} type-style-classes
 /// @requires {mixin} type-style-elements
+/// @example scss
+///   @include typography('Roboto', $my-type-scale);
 @mixin typography($font-family, $type-scale) {
     $scope: if(is-root(), ':root', '&');