igniteui-theming 18.0.0 → 18.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "igniteui-theming",
-  "version": "18.0.0",
+  "version": "18.0.2",
   "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

@@ -14,19 +14,53 @@
 ////
 
 /// @type String - The Element separator used. Default '__'.
-/// @access private
+/// @access public
+/// @example scss - Change the element separator from '__' to '-'
+///   $bem--sep-elem: '-';
+///
+///   @include b(block) {
+///      @include e(element) {
+///        background: blue;
+///      }
+///   }
+///
+///   // Generated CSS
+///   .block-element { background: blue; }
 $bem--sep-elem: if(meta.variable-exists(bem--sep-elem), $bem--sep-elem, '__');
 
 /// @type String - The Modifier separator used. Default '--'.
-/// @access private
+/// @access public
+/// @example scss - Change the modifier separator from '--' to '---'
+///   $bem--sep-mod: '---';
+///
+///   @include b(block) {
+///      @include m(modifier) {
+///        background: red;
+///      }
+///   }
+///
+///   // Generated CSS
+///   .block---modifier { background: red; }
 $bem--sep-mod: if(meta.variable-exists(bem--sep-mod), $bem--sep-mod, '--');
 
 /// @type String - The Modifier Value separator used. Default '-'.
-/// @access private
+/// @access public
+/// @example scss - Change the modifier value separator from '-' to '_'
+///   $bem--sep-mod-val: '_';
+///
+///   @include b(block) {
+///      @include m(modifier, value) {
+///        background: red;
+///      }
+///   }
+///
+///   // Generated CSS
+///   .block--modifier_value { background: red; }
 $bem--sep-mod-val: if(meta.variable-exists(bem--sep-mod-val), $bem--sep-mod-val, '-');
 
 /// Cache for modifier string conversions
 /// @type Map
+/// @access private
 $_bem-mod-cache: () !default;
 
 /// Converts a passed selector value into plain string.
@@ -190,23 +224,31 @@ $_bem-mod-cache: () !default;
 }
 
 /// Generates a full BEM selector.
-/// @access private
-/// @param {String} $block - Required. A string block name.
-/// @param {String|List} $elem - Optional. A sub-element name. If `$mod` is not present, it is
+/// @access public
+/// @param {String} $block - A string block name. Required.
+/// @param {String|List} $elem [null] - A sub-element name. If `$mod` is not present, it is
 /// joined with $block. If $mod is present, it is nested under `$block--$mod`.
-/// @param {String|Map} $mod - Optional. A block modifier.
+/// @param {String|Map} $mod [null] - A block modifier.
+/// @param {List} $mods [null] - A list of block modifiers.
+///
 /// @example scss Include a block
-///   @include bem-selector(block); // outputs .block
+///   $selector: bem-selector(block); // returns .block
+///
 /// @example scss Include a block and an element
-///   @include bem-selector(block, $e:elem); // outputs .block__elem
+///   $selector: bem-selector(block, $elem: elem); // returns .block__elem
+///
 /// @example scss Include block, element, and element modifier
-///   @include bem-selector(block, $e:(elem, $mod); // outputs .block__elem-emod
+///   $selector: bem-selector(block, $elem: (elem, mod); // returns .block__elem--mod
+///
 /// @example scss Include block and block modifier
-///   @include bem-selector(block, $m:mod) // outputs .block--mod
-/// @example scss Include block and modifier value
-///   @include bem-selector(block, $m:(mod:val)); // outputs .block--mod-val
+///   $selector: bem-selector(block, $mod: mod) // returns .block--mod
+///
+/// @example scss Include block and multiple block modifiers
+///   $selector: bem-selector(block, $mods: (mod-1, mod-2)) // returns .block--mod-1.block--mod-2
+///
 /// @example scss Include block modifier followed by block sub-element
-///   @include bem-selector(block, $m:mod, $e:elem); // outputs .block--mod .block__elem
+///   $selector: bem-selector(block, $m: mod, $e: elem); // returns .block--mod .block__elem
+///
 /// @return {String} The generated BEM selector string
 @function bem-selector($block, $e: null, $elem: null, $m: null, $mod: null, $mods: null) {
     $block: bem--with-dot($block);
@@ -284,11 +326,11 @@ $_bem-mod-cache: () !default;
 /// @access public
 /// @param {String} $block - The block name.
 /// @param {String} $elem - The element name.
-/// @param {String} $mod - Optional. The modifier name.
+/// @param {String} $mod [null] - The modifier name. Optional.
 /// @return {String} The BEM element selector string.
 /// @example scss
-///   elem('button', 'icon')        // returns '.button__icon'
-///   elem('button', 'icon', 'big') // returns '.button__icon--big'
+///   $selector: elem('button', 'icon') // returns '.button__icon'
+///   $selector: elem('button', 'icon', 'big') // returns '.button__icon--big'
 @function elem($block, $elem, $mod: null) {
     @if not meta.type-of($block) == 'string' {
         @error 'Block must be a string, got #{meta.type-of($block)}';
@@ -315,21 +357,22 @@ $_bem-mod-cache: () !default;
 /// @param {String} $mod - The modifier name.
 /// @return {String} The BEM modifier selector string.
 /// @example scss
-///   mod('button', 'primary') // returns '.button--primary'
-///   mod('card', 'outlined') // returns '.card--outlined'
+///   $selector: mod('button', 'primary') // returns '.button--primary'
+///   $selector: mod('card', 'outlined') // returns '.card--outlined'
 @function mod($block, $mod) {
     @return bem-selector($block, $m: $mod);
 }
 
 /// 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 scss
+/// @access public
 /// @param {String} $block - The block name.
 /// @example
 ///   @include bem-block(block) {
 ///      background: green;
 ///   }
-///   // Return
+///
+///   // Output
 ///   .block { background: green; }
 @mixin bem-block($block) {
     @at-root {
@@ -523,72 +566,137 @@ $_bem-mod-cache: () !default;
     }
 }
 
-/// @alias bem-selector
-/// @see bem-selector
+/// Generates a full BEM rule.
+/// @access public
+/// @param {String} $block - A string block name. Required.
+/// @param {String|List} $elem [null] - A sub-element name. If `$mod` is not present, it is
+/// joined with $block. If $mod is present, it is nested under `$block--$mod`.
+/// @param {String|Map} $mod [null] - A block modifier.
+/// @param {String|Map} $mods [null] - A list of block modifiers.
+///
+/// @example scss - Include a block
+///   @include bem(block) {
+///     background: blue;
+///   };
+///
+///   // Output
+///   .block {
+///     background: blue;
+///   }
+///
+/// @example scss - Include a block and an element
+///   @include bem(block, $elem: elem) {
+///     background: blue;
+///   }
+///
+///  // Output
+///   .block__elem {
+///     background: blue;
+///   }
+///
+/// @example scss - Include block, element, and element modifier
+///   @include bem(block, $elem: (elem, mod)) {
+///     background: blue;
+///   }
+///
+///   // Output
+///   .block__elem--mod {
+///     background: blue;
+///   }
+///
+/// @example scss - Include block and block modifier
+///   @include bem(block, $mod: mod) {
+///     background: blue;
+///   }
+///
+///   // Output
+///   .block--mod {
+///     background: blue;
+///   }
+///
+/// @example scss - Include block with multiple modifiers
+///  @include bem(block, $mods: (mod-1, mod-2)) {
+///     background: blue;
+///   }
+///
+///   // Output
+///   .block--mod-1.block--mod-2 {
+///     background: blue;
+///   }
+///
+/// @example scss - Include block modifier followed by block sub-element
+///   @include bem(block, $m:mod, $e:elem) {
+///     background: blue;
+///   }
+///
+///   // Output
+///   .block--mod .block__elem {
+///     background: blue;
+///   }
 @mixin bem($block, $e: null, $elem: null, $m: null, $mod: null, $mods: null) {
     #{bem-selector($block, $e: $e, $elem: $elem, $m: $m, $mod: $mod, $mods: $mods)} {
         @content;
     }
 }
 
+/// The same as bem-block.
 /// @alias bem-block
-/// @see bem-block
 @mixin block($block) {
     @include bem-block($block) {
         @content;
     }
 }
 
+/// The same as bem-elem.
 /// @alias bem-elem
-/// @see bem-elem
 @mixin elem($elem, $m: null, $mod: null, $mods: null, $not: null) {
     @include bem-elem($elem, $m: $m, $mod: $mod, $mods: $mods, $not: $not) {
         @content;
     }
 }
 
+/// The same as bem-mod.
 /// @alias bem-mod
-/// @see bem-mod
 @mixin mod($mod, $not: null) {
     @include bem-mod($mod, $not) {
         @content;
     }
 }
 
+/// The same as bem-mods.
 /// @alias bem-mods
-/// @see bem-mods
 @mixin mods($mods...) {
     @include bem-mods($mods...) {
         @content;
     }
 }
 
+/// The same as bem-block.
 /// @alias bem-block
-/// @see bem-block
 @mixin b($block) {
     @include bem-block($block) {
         @content;
     }
 }
 
+/// The same as bem-elem.
 /// @alias bem-elem
-/// @see bem-elem
 @mixin e($elem, $m: null, $mod: null, $mods: null, $not: null) {
     @include bem-elem($elem, $m: $m, $mod: $mod, $mods: $mods, $not: $not) {
         @content;
     }
 }
 
+/// The same as bem-mod.
 /// @alias bem-mod
-/// @see bem-mod
 @mixin m($mod, $not: null) {
     @include bem-mod($mod, $not) {
         @content;
     }
 }
 
+/// The same as bem-mods.
 /// @alias bem-mods
-/// @see bem-mods
 @mixin mx($mods...) {
     @include bem-mods($mods...) {
         @content;

package/sass/color/_functions.scss

@@ -18,11 +18,12 @@ $_enhanced-accessibility: false;
 /// Configures the color module.
 /// @access public
 /// @group color
-/// @param {Boolean} $enhanced-accessibility [null] - Enables features like color blind palettes.
+/// @param {Boolean} $enhanced-accessibility [null] - Enables features like color blind brushes for chart themes.
 /// @example scss
 ///   .enhanced-accessibility {
 ///      @include configure-colors(true);
 ///    }
+/// @see $brushes-color-blind
 @mixin configure-colors($enhanced-accessibility: null) {
     @if $enhanced-accessibility {
         $_enhanced-accessibility: $enhanced-accessibility !global;
@@ -44,8 +45,15 @@ $_enhanced-accessibility: false;
 /// @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);
+///   // Pass the required colors
+///   $my-palette: palette(
+///     $primary: rebeccapurple,
+///     $secondary: orange,
+///     $surface: white,
+///   );
+///
+///   // Include the generated palette colors as CSS variables.
+///   @include palette($my-palette);
 @function palette(
     $primary,
     $secondary,
@@ -83,18 +91,26 @@ $_enhanced-accessibility: false;
     );
 }
 
-/// Generates a Material-like color palette from a base color.
+/// Generates color shades for a given color.
 /// @access public
 /// @group Palettes
 /// @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. Useful when generating shades of gray (optional).
-/// @requires {function} shade
-/// @requires {function} text-contrast
-/// @returns {Map} - A map consisting of hsla color shades and their respective contrast colors.
+/// @param {Color} $color - The base color used to generate the shades.
+/// @param {List} $shades - The list of shade variants.
+/// @param {Color} $surface [null] - The surface color. Useful if generating shades of gray (optional).
+/// @requires {function} adaptive-contrast
+/// @returns {Map} - A map consisting of 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))
+///   $color-name: 'accent';
+///
+///   // Include the generated palette colors as CSS variables.
+///   @include palette(
+///     (
+///       #{$color-name}: shades($color-name, #a57865, $IColorShades),
+///     )
+///   );
+/// @see $IColorShades
 @function shades($name, $color, $shades, $surface: null) {
     $result: ();
 
@@ -161,9 +177,6 @@ $_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
@@ -172,14 +185,26 @@ $_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
+///
+/// @example scss - Getting a color from the palette
+///   // Without providing a palette
 ///   .my-component-1 {
-///      background: color($color: 'primary', $variant: 200);
+///      background: color($color: primary, $variant: 200); // var(--ig-primary-200)
 ///    }
-///    // Using certain palette and adding .5% opacity to the color variant
+///
+///    // With a specific palette
 ///   .my-component-2 {
-///      background: color($my-palette, 'primary', 200, .5);
+///      background: color($my-palette, primary, 200); // #88c0e5
+///    }
+///
+/// @example scss - Getting a color with opacity
+///   .my-component-1 {
+///      background: color($color: primary, $variant: 200, $opacity: 0.5); // hsl(from var(--ig-primary-200) h s l/0.5)
+///    }
+///
+///    // With a specific palette
+///   .my-component-2 {
+///      background: color($my-palette, primary, 200, $opacity: 0.5); // rgba(136, 192, 229, 0.5)
 ///    }
 @function color($palette: null, $color: primary, $variant: 500, $opacity: null) {
     $s: #{var(--ig-#{$color}-#{$variant})};
@@ -198,7 +223,7 @@ $_enhanced-accessibility: false;
     @return $_relative-color;
 }
 
-/// Retrieves a contrast text color for a given color variant from a color palette.
+/// Retrieves a contrast color for a given color variant from a color palette. Works similarly to the color function.
 /// @access public
 /// @group Palettes
 /// @param {Map} $palette [null] - The source palette map (optional).
@@ -207,11 +232,13 @@ $_enhanced-accessibility: false;
 /// @param {Number} $opacity [null] - Optional opacity to apply to the color shade.
 /// @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, $opacity: null) {
     @return color($palette, $color, #{$variant}-contrast, $opacity);
 }
@@ -220,13 +247,14 @@ $_enhanced-accessibility: false;
 /// @access public
 /// @group Color
 /// @param {Color} $color - The base color used in the calculation.
-/// @returns {string} - Returns a relative syntax OKLCH color where the lightness is adjusted
+/// @returns {string} - Returns a relative HSL color where the lightness is adjusted
 /// based on the specified contrast level, resulting in either black or white.
+///
 /// @example scss
 ///   .my-component {
 ///      --bg: #09f;
 ///      background: var(--bg);
-///      color: adaptive-contrast(var(--bg));
+///      color: adaptive-contrast(var(--bg)); // hsl(from color(from var(--bg) var(--y-contrast)) h 0 l)
 ///    }
 @function adaptive-contrast($color) {
     $fn: meta.get-function('color', $css: true);
@@ -235,6 +263,7 @@ $_enhanced-accessibility: false;
 }
 
 /// Returns a contrast color for a passed color.
+/// @deprecated Use adaptive-contrast instead.
 /// @access public
 /// @group Color
 /// @param {Color} $background - The background color used to return a contrast/forground color for.
@@ -244,12 +273,15 @@ $_enhanced-accessibility: false;
 /// @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
+///
 /// @example scss
 ///   .my-component {
-///      background: #09f
-///      color: text-contrast(#09f)
+///      background: #09f;
+///      color: text-contrast(#09f);
 ///    }
+///
+/// @see {function} adaptive-contrast
+/// @link https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html WCAG 2.0 Contrast
 @function text-contrast($background, $foreground: white, $contrast: 'AAA') {
     @if meta.type-of($foreground) != 'list' and meta.type-of($background) != 'color' {
         @return $background;
@@ -295,6 +327,7 @@ $_enhanced-accessibility: false;
 }
 
 /// Mixes two colors to produce an opaque color.
+/// @deprecated Switch to CSS color-mix.
 /// @access private
 /// @group Color
 /// @param {Color} $color-1 - The first color, usually transparent.
@@ -317,6 +350,7 @@ $_enhanced-accessibility: false;
 }
 
 /// Retruns a comma separated list of hue, saturation, and lightness values for a given color.
+/// @deprecated Not needed anymore and will be removed in the future.
 /// @access public
 /// @group Color
 /// @param {Color} $color - The color to be converted to an HSL list of values.
@@ -328,16 +362,18 @@ $_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
+///
 /// @example scss
-///   contrast(#09f, #000);
+///   $conrast: contrast(#09f, #000); // 7
+///
 /// @returns {Number} - The contrast ratio between the background and foreground colors.
+/// @require {function} luminance
+/// @require {function} to-fixed
+/// @link https://www.w3.org/TR/WCAG20-TECHS/G17.html#G17-tests WCAG 2.0 Contrast Ratio
 @function contrast($background, $foreground) {
     $backLum: luminance($background) + 0.05;
     $foreLum: luminance($foreground) + 0.05;
@@ -346,13 +382,17 @@ $_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.
+///
 /// @example scss
-///   luminance(#09f);
+///   $white: luminance(#fff); // 1
+///   $blue: luminance(#09f); // 0.3
+///   $black: luminance(#000); // 0
+///
 /// @returns {Number | String} - The calculated luminance of a given color
+/// @link https://www.w3.org/TR/WCAG20-TECHS/G17.html#G17-tests. WCAG 2.0 Contrast Ratio
 @function luminance($color) {
     @if meta.type-of($color) == 'color' {
         $r: math.div(color.red($color), 255);
@@ -375,10 +415,13 @@ $_enhanced-accessibility: false;
     @return if($value < 0.03928, math.div($value, 12.92), math.pow(math.div($value + 0.055, 1.055), 2.4));
 }
 
-/// Returns a list of colors to be used as chart brushes.
+/// Returns a list of colors to be used as chart brushes. The return value depends on the value of enhanced-accessibility.
 /// @access public
 /// @group Palettes
 /// @returns { List } - A list of colors to be used as chart brushes.
+/// @see {mixin} configure-colors
+/// @see $brushes-regular
+/// @see $brushes-color-blind
 @function chart-brushes() {
     @return if($_enhanced-accessibility, charts.$brushes-color-blind, charts.$brushes-regular);
 }

package/sass/color/_mixins.scss

@@ -30,19 +30,22 @@ $_added: () !default;
 }
 
 /// Sets up CSS custom properties for WCAG contrast calculations.
-/// These properties are used to determine the appropriate text color contrast
+/// These properties are used to determine the appropriate text contrast color
 /// based on WCAG accessibility guidelines.
 /// @access public
 /// @group Color
 /// @param {String} $level ['aa'] - WCAG contrast level ('a', 'aa', or 'aaa')
+///
 /// @example scss - Using the mixin with default AA level
 ///   .my-component {
 ///     @include adaptive-contrast();
 ///   }
+///
 /// @example scss - Using the mixin with AAA level
 ///   .my-component {
 ///     @include adaptive-contrast('aaa');
 ///   }
+///
 /// @example scss - Generated CSS custom properties
 ///   :root {
 ///     --ig-wcag-a: 0.31;    // Level A threshold
@@ -70,10 +73,14 @@ $_added: () !default;
 /// @group Palettes
 /// @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
+/// @require {function} to-string
+/// @require {mixin} adaptive-contrast
 @mixin palette($palette, $contrast: true, $contrast-level: 'aa') {
     $scope: if(is-root(), ':root', '&');
 

package/sass/color/_types.scss

@@ -8,17 +8,20 @@
 
 /// A list consisting of all generated gray shades
 /// @type Map
-/// @access private
+/// @access public
 $IGrayShades: ('50', '100', '200', '300', '400', '500', '600', '700', '800', '900');
 
 /// A list consisting of all generated shades for palette colors
 /// @type Map
-/// @access private
+/// @access public
+/// @requires $IGrayShades
 $IColorShades: list.join($IGrayShades, ('A100', 'A200', 'A400', 'A700'));
 
 /// All palette colors mapped with corresponding color shades
 /// @type Map
-/// @access private
+/// @access public
+/// @requires $IColorShades
+/// @requires $IGrayShades
 $IPaletteColors: (
     'primary': $IColorShades,
     'secondary': $IColorShades,
@@ -40,6 +43,7 @@ $IPaletteMeta: (
 /// A map with all palette colors and palette meta
 /// @type Map
 /// @access private
+/// @requires $IPaletteColors
 $IPalette: map.merge(
     $IPaletteColors,
     (

package/sass/elevations/_functions.scss

@@ -53,11 +53,16 @@ $factor: var(--ig-elevation-factor, 1);
 /// @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;
+///   .my-component {
+///     box-shadow: box-shadow((0 0 2px 3px black, 0 6px 9px orange));
+///   }
+///
+///   // Output
+///   .my-component {
+///     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
@@ -90,8 +95,8 @@ $factor: var(--ig-elevation-factor, 1);
 /// @access public
 /// @param {String} $name - The name of the shadow.
 /// @example scss
-///   .my-class {
-///     box-shadow: elevation(5);
+///   .my-component {
+///     box-shadow: elevation(5); // var(--ig-elevation-5)
 ///   }
 /// @return {String} - The CSS elevation variable
 @function elevation($name) {