igniteui-theming 1.0.0-beta.1 → 1.0.0-beta.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "igniteui-theming",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.10",
   "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/color/_functions.scss

@@ -7,13 +7,13 @@
 @use 'charts';
 @use 'multipliers';
 @use 'types';
-@use '../utils' as *;
+@use '../utils/math' as *;
 
 $_enhanced-accessibility: false;
 
 /// Configures the color module.
 /// @access public
-/// @param {Boolean} $enhanced-accessibility - Enables features like color blind palettes.
+/// @param {Boolean} $enhanced-accessibility [null] - Enables features like color blind palettes.
 @mixin configure($enhanced-accessibility: null) {
     @if $enhanced-accessibility {
         $_enhanced-accessibility: $enhanced-accessibility !global;
@@ -23,7 +23,6 @@ $_enhanced-accessibility: false;
 /// Generates a color palette.
 /// @access public
 /// @group Palettes
-/// @requires {function} _color-palette
 /// @param {Color} $primary - The primary color used to generate the primary color palette (required).
 /// @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).
@@ -33,7 +32,8 @@ $_enhanced-accessibility: false;
 /// @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 {String} $variant [null] - Used internally (optional).
-/// @returns {Map} - A map consisting of color shades for the passed base colors(primary, secondary, gray, etc).
+/// @requires {function} shades
+/// @returns {Map} - A map consisting of color shades for the passed base colors (primary, secondary, gray, etc).
 @function palette(
     $primary,
     $secondary,
@@ -47,26 +47,26 @@ $_enhanced-accessibility: false;
 ) {
     $color-shades: map.keys(types.$IColorShades);
     $gray-shades: map.keys(types.$IGrayShades);
-    $primary-palette: shades(primary, $primary, $color-shades);
-    $secondary-palette: shades(secondary, $secondary, $color-shades);
-    $surface-palette: shades(surface, $surface, $color-shades);
-    $grayscale-palette: shades(gray, $gray, $gray-shades, $surface);
-    $info-palette: if($info, shades(info, $info, $color-shades), ());
-    $success-palette: if($success, shades(success, $success, $color-shades), ());
-    $warn-palette: if($warn, shades(warn, $warn, $color-shades), ());
-    $error-palette: if($success, shades(error, $error, $color-shades), ());
+    $primary-palette: shades('primary', $primary, $color-shades);
+    $secondary-palette: shades('secondary', $secondary, $color-shades);
+    $surface-palette: shades('surface', $surface, $color-shades);
+    $grayscale-palette: shades('gray', $gray, $gray-shades, $surface);
+    $info-palette: if($info, shades('info', $info, $color-shades), ());
+    $success-palette: if($success, shades('success', $success, $color-shades), ());
+    $warn-palette: if($warn, shades('warn', $warn, $color-shades), ());
+    $error-palette: if($success, shades('error', $error, $color-shades), ());
 
     @return (
-        primary: $primary-palette,
-        secondary: $secondary-palette,
-        gray: $grayscale-palette,
-        surface: $surface-palette,
-        info: $info-palette,
-        success: $success-palette,
-        warn: $warn-palette,
-        error: $error-palette,
-        _meta: (
-            variant: $variant,
+        'primary': $primary-palette,
+        'secondary': $secondary-palette,
+        'gray': $grayscale-palette,
+        'surface': $surface-palette,
+        'info': $info-palette,
+        'success': $success-palette,
+        'warn': $warn-palette,
+        'error': $error-palette,
+        '_meta': (
+            'variant': $variant,
         )
     );
 }
@@ -78,10 +78,8 @@ $_enhanced-accessibility: false;
 /// @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).
-/// @requires {function} _color-shade
-/// @requires {function} _hsla-shade
-/// @requires {function} contrast
-/// @requires {function} to-opaque
+/// @requires {function} shade
+/// @requires {function} text-contrast
 /// @returns {Map} - A map consisting of hsla color shades and thier respective contrast colors.
 @function shades(
     $name,
@@ -113,6 +111,8 @@ $_enhanced-accessibility: false;
 /// @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).
+/// @require {function} luminance
+/// @require {function} to-fixed
 /// @returns {Map} - A map containing a list of HSL values and a raw color value.
 @function shade(
     $name,
@@ -124,7 +124,7 @@ $_enhanced-accessibility: false;
     $s: var(--ig-#{$name}-s);
     $l: var(--ig-#{$name}-l);
 
-    @if $name == gray {
+    @if #{$name} == 'gray' {
         $lum: luminance($surface);
         $color: if($color, $color, if($lum > .5, #000, #fff));
         $lmap: map.get(multipliers.$grayscale, 'l');
@@ -158,13 +158,13 @@ $_enhanced-accessibility: false;
 /// Retrieves a color from a color palette.
 /// @access public
 /// @group Palettes
-/// @param {Map} $palette [null]- The source palette map (optional).
-/// @param {String} $color [primary]- The target color from the color palette.
+/// @param {Map} $palette [null] - The source palette map (optional).
+/// @param {String} $color [primary] - The target color from the color palette.
 /// @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.
-@function color($palette: null, $color: primary, $variant: 500, $opacity: null) {
-    $c: map.get($palette or types.$IPalette, $color);
+@function color($palette: null, $color: 'primary', $variant: 500, $opacity: null) {
+    $c: map.get($palette or types.$IPalette, #{$color});
     $a: var(--ig-#{$color}-a);
     $s: #{var(--ig-#{$color}-#{$variant})};
     $contrast: if(
@@ -175,7 +175,7 @@ $_enhanced-accessibility: false;
     $meta: if($palette, map.get($palette, '_meta'), null);
 
     @if not($c) {
-        @error 'The passed color #{$color} is not valid.';
+        @error 'The passed color #{meta.inspect($color)} is not valid.';
     }
 
     @if not($palette) or not($meta) {
@@ -191,11 +191,11 @@ $_enhanced-accessibility: false;
 
 /// Retrieves a contrast text color for a given color from a color palette.
 /// @access public
-/// @group Palettesreference
-/// @param {Map} $palette [null]- The source palette map (optional).
-/// @param {String} $color [primary]- The target color from the color palette.
+/// @group Palettes
+/// @param {Map} $palette [null] - The source palette map (optional).
+/// @param {String} $color [primary] - The target color from the color palette.
 /// @param {Number | String} $variant [500] - The target color shade from the color palette.
-/// @requires color
+/// @requires {function} color
 /// @returns {Color | String} - The raw contrast color shade or CSS variable from the palette.
 @function contrast-color($palette: null, $color: primary, $variant: 500) {
     @return color($palette, $color, #{$variant}-contrast);
@@ -208,6 +208,7 @@ $_enhanced-accessibility: false;
 /// @param {Color | List<Color>} $foreground [#fff] - A list of foreground colors
 /// that can be used with the provided background.
 /// @param {AAA | AA | A} $contrast [AAA] - The contrast level according to WCAG 2.0 standards.
+/// @require {function} contrast
 /// @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
@@ -261,6 +262,7 @@ $_enhanced-accessibility: false;
 
 /// Mixes two colors to produce an opaque color.
 /// @access public
+/// @group Color
 /// @param {Color} $color-1 - The first color, usually transparent.
 /// @param {Color} $color-2 [#fff] - The second color, usually opaque.
 /// @return {Color} - The color representation of the rgba value.
@@ -282,6 +284,7 @@ $_enhanced-accessibility: false;
 
 /// Retruns a comma separated list of hue, saturation, and lightness values for a given color.
 /// @access public
+/// @group Color
 /// @param {Color} $color - The color to be converted to an HSL list of values.
 /// @example scss Turn #000 into an HSL list of values
 ///   $hsl-list: to-hsl(#000); // (0deg, 0%, 0%);
@@ -292,9 +295,12 @@ $_enhanced-accessibility: false;
 
 /// Calculates the contrast ratio between two colors.
 /// See https://www.w3.org/TR/WCAG20-TECHS/G17.html#G17-tests
-///
+/// @access public
+/// @group Color
 /// @param {Color} $background - The background color.
 /// @param {Color} $foreground - The foreground color.
+/// @require {function} luminance
+/// @require {function} to-fixed
 /// @returns {Number} - The contrast ratio between the background and foreground colors.
 @function contrast($background, $foreground) {
     $backLum: luminance($background) + .05;
@@ -305,8 +311,10 @@ $_enhanced-accessibility: false;
 
 /// Calculates the luminance for a given color.
 /// See https://www.w3.org/TR/WCAG20-TECHS/G17.html#G17-tests.
-///
+/// @access public
+/// @group Color
 /// @param {Color} $color - The color to calculate luminance for.
+/// @returns {Number | String} - The calculated luminance of a given color
 @function luminance($color) {
     @if meta.type-of($color) == 'color' {
         $r: math.div(color.red($color), 255);
@@ -321,6 +329,9 @@ $_enhanced-accessibility: false;
 
 /// Calculates the linear channel value for a given sRGB color.
 /// @access private
+/// @group Color
+/// @param {Number} $value - The sRGB color
+/// @returns {Number} - The calculated linear channel value
 @function _lcv($value) {
     /* stylelint-disable number-max-precision */
     @return if(
@@ -337,12 +348,3 @@ $_enhanced-accessibility: false;
 @function chart-brushes() {
     @return if($_enhanced-accessibility, charts.$brushes-color-blind, charts.$brushes-regular);
 }
-
-/// Returns a list of H, S, L values for a given color.
-/// @access public
-/// @param {Color} $color - The color to generate HSL values for.
-/// @group Palettes
-/// @returns { List } - The list of values.
-@function to-hsl($color) {
-    @return (color.hue($color), color.saturation($color), color.lightness($color));
-}

package/sass/color/_mixins.scss

@@ -8,12 +8,12 @@
 /// Generates CSS variables for a given palette.
 /// @access public
 /// @group Palettes
-/// @param {Map} $palette [null] - The palette used to generate CSS variables.
+/// @param {Map} $palette - The palette used to generate CSS variables.
 /// @param {Boolean} $contrast [true] - Specify if contrast colors should be included.
 /// @example scss Generate css variables for a palette
 ///    $palette: palette($primary: red, $secondary: blue, $gray: #000);
 ///    @include palette($palette);
-///
+/// @require {function} is-root
 @mixin palette($palette, $contrast: true) {
     $scope: if(is-root(), ':root', '&');
 
@@ -27,20 +27,20 @@
                 $_contrast: if($_other-shade, string.index($shade, 'contrast'), false);
 
                 @if $_base-shade and $_valid-color {
-                    --ig-#{meta.inspect($color)}-h: #{math.round(color.hue($value))};
-                    --ig-#{meta.inspect($color)}-s: #{math.round(color.saturation($value))};
-                    --ig-#{meta.inspect($color)}-l: #{math.round(color.lightness($value))};
-                    --ig-#{meta.inspect($color)}-a: #{color.alpha($value)};
+                    --ig-#{$color}-h: #{math.round(color.hue($value))};
+                    --ig-#{$color}-s: #{math.round(color.saturation($value))};
+                    --ig-#{$color}-l: #{math.round(color.lightness($value))};
+                    --ig-#{$color}-a: #{color.alpha($value)};
                 }
 
                 @if $_hsl {
                     $variant: string.slice($shade, 1, string.index($shade, '-hsl') - 1);
 
-                    --ig-#{meta.inspect($color)}-#{$variant}: #{$value};
+                    --ig-#{$color}-#{$variant}: #{$value};
                 }
 
                 @if $_contrast and $contrast {
-                    --ig-#{meta.inspect($color)}-#{$shade}: #{$value};
+                    --ig-#{$color}-#{$shade}: #{$value};
                 }
             }
         }

package/sass/color/_types.scss

@@ -1,5 +1,11 @@
 @use 'sass:map';
 
+////
+/// @group Palettes
+////
+
+/// A list consisting of all generated gray shades
+/// @type Map
 $IGrayShades: (
     50: '',
     100: '',
@@ -12,6 +18,9 @@ $IGrayShades: (
     800: '',
     900: '',
 );
+
+/// A list consisting of all generated shades for palette colors
+/// @type Map
 $IColorShades: map.merge(
     $IGrayShades,
     (
@@ -21,17 +30,26 @@ $IColorShades: map.merge(
         'A700': '',
     )
 );
+
+/// All palette colors mapped with corresponding color shades
+/// @type Map
 $IPaletteColors: (
-    primary: $IColorShades,
-    secondary: $IColorShades,
-    gray: $IGrayShades,
-    surface: $IColorShades,
-    info: $IColorShades,
-    success: $IColorShades,
-    warn: $IColorShades,
-    error: $IColorShades,
+    'primary': $IColorShades,
+    'secondary': $IColorShades,
+    'gray': $IGrayShades,
+    'surface': $IColorShades,
+    'info': $IColorShades,
+    'success': $IColorShades,
+    'warn': $IColorShades,
+    'error': $IColorShades,
 );
+
+/// A list consisting of palette metadata
+/// @type Map
 $IPaletteMeta: (
-    variant: '',
+    'variant': '',
 );
+
+/// A map with all palette colors and palette meta
+/// @type Map
 $IPalette: map.merge($IPaletteColors, (_meta: $IPaletteMeta));

package/sass/color/presets/_index.scss

@@ -0,0 +1,2 @@
+@forward 'light';
+@forward 'dark';

package/sass/color/presets/dark/_bootstrap.scss

@@ -0,0 +1,13 @@
+@use '../../functions' as *;
+
+$palette: palette(
+    $primary: #0d6efd,
+    $secondary: #6c757d,
+    $gray: #adb5bd,
+    $surface: #212529,
+    $info: #0dcaf0,
+    $success: #198754,
+    $warn: #ffc107,
+    $error: #dc3545,
+    $variant: 'bootstrap'
+);

package/sass/color/presets/dark/_extra.scss

@@ -0,0 +1,12 @@
+@use '../../functions' as *;
+
+$green-palette: palette(
+    $primary: #09f,
+    $secondary: #72da67,
+    $surface: #222,
+);
+$purple-palette: palette(
+    $primary: #00b4d6,
+    $secondary: #514590,
+    $surface: #333,
+);

package/sass/color/presets/dark/_fluent.scss

@@ -0,0 +1,29 @@
+@use '../../functions' as *;
+
+$palette: palette(
+    $primary: #0078d4,
+    $secondary: #0078d4,
+    $surface: #222,
+    $success: #107c10,
+    $warn: #797673,
+    $error: #a80000,
+    $variant: 'fluent'
+);
+$word-palette: palette(
+    $primary: #2b579a,
+    $secondary: #2b579a,
+    $surface: #222,
+    $success: #107c10,
+    $warn: #797673,
+    $error: #a80000,
+    $variant: 'fluent'
+);
+$excel-palette: palette(
+    $primary: #217346,
+    $secondary: #217346,
+    $surface: #222,
+    $success: #107c10,
+    $warn: #797673,
+    $error: #a80000,
+    $variant: 'fluent'
+);

package/sass/color/presets/dark/_index.scss

@@ -0,0 +1,5 @@
+@forward 'material' as dark-material-*;
+@forward 'bootstrap' as dark-bootstrap-*;
+@forward 'fluent' as dark-fluent-*;
+@forward 'indigo' as dark-indigo-*;
+@forward 'extra' as dark-*;

package/sass/color/presets/dark/_indigo.scss

@@ -0,0 +1,13 @@
+@use '../../functions' as *;
+
+$palette: palette(
+    $primary: #3f51b5,
+    $secondary: #3f51b5,
+    $gray: hsl(262deg 8% 98%),
+    $surface: #2a2b2f,
+    $info: #9208bc,
+    $success: #689f38,
+    $warn: #ff9800,
+    $error: #cf1a2b,
+    $variant: 'indigo'
+);

package/sass/color/presets/dark/_material.scss

@@ -0,0 +1,12 @@
+@use '../../functions' as *;
+
+$palette: palette(
+    $primary: #09f,
+    $secondary: #e41c77,
+    $surface: #222,
+    $info: #1377d5,
+    $success: #4eb862,
+    $warn: #fbb13c,
+    $error: #ff134a,
+    $variant: 'material'
+);

package/sass/color/presets/light/_bootstrap.scss

@@ -0,0 +1,13 @@
+@use '../../functions' as *;
+
+$palette: palette(
+    $primary: #0d6efd,
+    $secondary: #6c757d,
+    $gray: #adb5bd,
+    $surface: #f8f9fa,
+    $info: #0dcaf0,
+    $success: #198754,
+    $warn: #ffc107,
+    $error: #dc3545,
+    $variant: 'bootstrap'
+);

package/sass/color/presets/light/_extra.scss

@@ -0,0 +1,12 @@
+@use '../../functions' as *;
+
+$green-palette: palette(
+    $primary: #09f,
+    $secondary: #72da67,
+    $surface: #fff
+);
+$purple-palette: palette(
+    $primary: #00b4d6,
+    $secondary: #514590,
+    $surface: #fff
+);

package/sass/color/presets/light/_fluent.scss

@@ -0,0 +1,30 @@
+@use '../../functions' as *;
+
+$palette: palette(
+    $primary: #0078d4,
+    $secondary: #0078d4,
+    $surface: #fff,
+    $info: #1377d5,
+    $success: #107c10,
+    $warn: #797673,
+    $error: #a80000,
+    $variant: 'fluent'
+);
+$word-palette: palette(
+    $primary: #2b579a,
+    $secondary: #2b579a,
+    $surface: #fff,
+    $success: #107c10,
+    $warn: #797673,
+    $error: #a80000,
+    $variant: 'fluent'
+);
+$excel-palette: palette(
+    $primary: #217346,
+    $secondary: #217346,
+    $surface: #fff,
+    $success: #107c10,
+    $warn: #797673,
+    $error: #a80000,
+    $variant: 'fluent'
+);

package/sass/color/presets/light/_index.scss

@@ -0,0 +1,5 @@
+@forward 'material' as light-material-*;
+@forward 'bootstrap' as light-bootstrap-*;
+@forward 'fluent' as light-fluent-*;
+@forward 'indigo' as light-indigo-*;
+@forward 'extra' as light-*;

package/sass/color/presets/light/_indigo.scss

@@ -0,0 +1,13 @@
+@use '../../functions' as *;
+
+$palette: palette(
+    $primary: #3f51b5,
+    $secondary: #3f51b5,
+    $gray: hsl(236deg 8% 5%),
+    $surface: #fff,
+    $info: #9208bc,
+    $success: #689f38,
+    $warn: #ff9800,
+    $error: #cf1a2b,
+    $variant: 'indigo'
+);

package/sass/color/presets/light/_material.scss

@@ -0,0 +1,12 @@
+@use '../../functions' as *;
+
+$palette: palette(
+    $primary: #09f,
+    $secondary: #e41c77,
+    $surface: white,
+    $info: #1377d5,
+    $success: #4eb862,
+    $warn: #fbb13c,
+    $error: #ff134a,
+    $variant: 'material'
+);

package/sass/elevations/_functions.scss

@@ -3,7 +3,7 @@
 @use 'sass:list';
 
 ////
-/// @group elevations
+/// @group Elevations
 ////
 
 $factor: var(--ig-elevation-factor, 1);
@@ -82,6 +82,7 @@ $factor: var(--ig-elevation-factor, 1);
 /// Gets a CSS elevation variable by name.
 /// @access public
 /// @param {String} $name - The name of the shadow.
+/// @return {String} - The CSS elevation variable
 @function elevation($name) {
     @return var(--ig-elevation-#{$name});
 }

package/sass/elevations/_mixins.scss

@@ -1,7 +1,7 @@
-@use '../utils' as *;
+@use '../utils/meta' as *;
 
 ////
-/// @group elevations
+/// @group Elevations
 ////
 
 /// Generates CSS variables for a given elevations map.
@@ -9,13 +9,13 @@
 /// @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);
-///
+///   $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);
+/// @require {function} is-root
 @mixin elevations($elevations) {
     $scope: if(is-root(), ':root', '&');
 

package/sass/elevations/presets/_index.scss

@@ -0,0 +1 @@
+@forward './material' as material-*;