igniteui-theming 1.0.0-alpha → 1.0.0-beta.3

package/.github/workflows/npm-publish.yml

@@ -21,6 +21,9 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Lint package
+        run: npm run lint
+
       - name: Test package
         run: npm test
 

package/.stylelintrc.json

@@ -0,0 +1,83 @@
+{
+    "extends": "stylelint-config-standard-scss",
+    "plugins": ["stylelint-scss"],
+    "rules": {
+        "at-rule-disallowed-list": ["debug", {
+            "severity": "warning"
+        }],
+        "block-closing-brace-empty-line-before": "never",
+        "block-closing-brace-newline-after": "always-single-line",
+        "block-no-empty": true,
+        "color-hex-case": "lower",
+        "color-hex-length": "short",
+        "color-no-invalid-hex": true,
+        "comment-no-empty": true,
+        "custom-property-pattern": "(?:igc-)?.+",
+        "declaration-block-no-duplicate-properties": true,
+        "declaration-block-no-shorthand-property-overrides": true,
+        "declaration-block-single-line-max-declarations": 1,
+        "declaration-colon-space-after": "always-single-line",
+        "font-family-no-duplicate-names": true,
+        "font-family-no-missing-generic-family-keyword": true,
+        "font-weight-notation": "numeric",
+        "function-calc-no-unspaced-operator": true,
+        "function-comma-space-after": "always-single-line",
+        "indentation": 4,
+        "length-zero-no-unit": true,
+        "max-nesting-depth": [3, {
+            "severity": "warning"
+        }],
+        "no-descending-specificity": null,
+        "no-duplicate-at-import-rules": true,
+        "no-duplicate-selectors": true,
+        "no-extra-semicolons": true,
+        "no-invalid-double-slash-comments": true,
+        "no-missing-end-of-source-newline": true,
+        "number-leading-zero": "never",
+        "number-no-trailing-zeros": true,
+        "property-no-unknown": true,
+        "rule-empty-line-before": ["always-multi-line", {
+            "except": ["first-nested"],
+            "ignore": ["after-comment"]
+        }],
+        "selector-attribute-quotes": "always",
+        "selector-attribute-operator-space-after": "never",
+        "selector-attribute-operator-space-before": "never",
+        "selector-combinator-space-after": "always",
+        "selector-combinator-space-before": "always",
+        "selector-descendant-combinator-no-non-space": true,
+        "selector-list-comma-newline-after": "always",
+        "selector-pseudo-class-case": "lower",
+        "selector-pseudo-class-no-unknown": true,
+        "selector-pseudo-class-parentheses-space-inside": "never",
+        "selector-pseudo-element-case": "lower",
+        "selector-pseudo-element-colon-notation": "double",
+        "selector-pseudo-element-no-unknown": true,
+        "selector-type-case": "lower",
+        "selector-type-no-unknown": [true, {
+            "ignore": ["custom-elements"]
+        }],
+        "shorthand-property-no-redundant-values": true,
+        "string-quotes": "single",
+        "unit-case": "lower",
+        "value-keyword-case": "lower",
+        "value-list-comma-space-after": "always-single-line",
+        "value-no-vendor-prefix": true,
+        "scss/at-mixin-pattern": null,
+        "scss/at-function-pattern": null,
+        "scss/dollar-variable-pattern": null,
+        "scss/at-else-closing-brace-newline-after": "always-last-in-chain",
+        "scss/at-else-closing-brace-space-after": "always-intermediate",
+        "scss/at-else-empty-line-before": "never",
+        "scss/at-if-closing-brace-newline-after": "always-last-in-chain",
+        "scss/at-if-closing-brace-space-after": "always-intermediate",
+        "scss/at-import-no-partial-leading-underscore": true,
+        "scss/at-mixin-argumentless-call-parentheses": "always",
+        "scss/at-mixin-parentheses-space-before": "never",
+        "scss/at-rule-no-unknown": true,
+        "scss/double-slash-comment-inline": "never",
+        "scss/dollar-variable-colon-newline-after": null,
+        "scss/dollar-variable-colon-space-after": "always",
+        "scss/selector-no-redundant-nesting-selector": true
+    }
+}

package/_index.scss

@@ -1,2 +1,5 @@
-@forward './sass/functions';
-@forward './sass/mixins';
+@forward './sass/color';
+@forward './sass/typography';
+@forward './sass/elevations';
+@forward './sass/utils';
+@forward './sass/themes';

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "igniteui-theming",
-  "version": "1.0.0-alpha",
+  "version": "1.0.0-beta.3",
   "description": "A set of Sass variables, mixins, and functions for generating palettes, typography, and elevations used by Ignite UI components.",
   "main": "index.js",
   "scripts": {
-    "test": "jest"
+    "build:docs": "npx sassdoc ./sass",
+    "build:e2e": "sass ./test/e2e/theme.scss ./test/e2e/theme.css",
+    "lint": "stylelint ./sass",
+    "test": "jest",
+    "serve:docs": "npx http-server ./sassdoc"
   },
   "repository": {
     "type": "git",
@@ -35,9 +39,13 @@
   },
   "devDependencies": {
     "jest": "^28.1.1",
-    "sass-true": "^6.1.0"
+    "postcss": "^8.4.14",
+    "sass-true": "^6.1.0",
+    "stylelint": "^14.9.1",
+    "stylelint-config-standard-scss": "^4.0.0",
+    "stylelint-scss": "^4.2.0"
   },
   "peerDependencies": {
-    "sass": "^1.52.3"
+    "sass": "^1.53.0"
   }
 }

package/sass/_index.scss

@@ -0,0 +1,5 @@
+@forward 'color';
+@forward 'elevations';
+@forward 'typography';
+@forward 'utils';
+@forward 'themes';

package/sass/color/_charts.scss

@@ -0,0 +1,31 @@
+/// A list of color values to be used as brushes in charts.
+/// @type List
+/// @access public
+$brushes-regular: (
+    rgb(157 231 114),
+    rgb(139 91 177),
+    rgb(109 177 255),
+    rgb(154 242 228),
+    rgb(238 88 121),
+    rgb(115 86 86),
+    rgb(247 210 98),
+    rgb(168 168 183),
+    rgb(224 81 169),
+    rgb(248 161 95),
+);
+
+/// A list of color values to be used as color-blind brushes in charts.
+/// @type List
+/// @access public
+$brushes-color-blind: (
+    rgb(86 180 233),
+    rgb(0 158 115),
+    rgb(240 228 68),
+    rgb(213 94 0),
+    rgb(214 0 254),
+    rgb(0 73 159),
+    rgb(230 159 0),
+    rgb(0 0 0),
+    rgb(132 240 223),
+    rgb(115 86 86)
+);

package/sass/color/_functions.scss

@@ -0,0 +1,348 @@
+@use 'sass:map';
+@use 'sass:meta';
+@use 'sass:math';
+@use 'sass:list';
+@use 'sass:color';
+@use 'sass:string';
+@use 'charts';
+@use 'multipliers';
+@use 'types';
+@use '../utils' as *;
+
+$_enhanced-accessibility: false;
+
+/// Configures the color module.
+/// @access public
+/// @param {Boolean} $enhanced-accessibility - Enables features like color blind palettes.
+@mixin configure($enhanced-accessibility: null) {
+    @if $enhanced-accessibility {
+        $_enhanced-accessibility: $enhanced-accessibility !global;
+    }
+}
+
+/// 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).
+/// @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 {String} $variant [null] - Used internally (optional).
+/// @returns {Map} - A map consisting of color shades for the passed base colors(primary, secondary, gray, etc).
+@function palette(
+    $primary,
+    $secondary,
+    $surface,
+    $gray: null,
+    $info: null,
+    $success: null,
+    $warn: null,
+    $error: null,
+    $variant: null,
+) {
+    $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), ());
+
+    @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,
+        )
+    );
+}
+
+/// Generates a Material-like color palette from a base 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. Usefull when generating shades of gray (optional).
+/// @requires {function} _color-shade
+/// @requires {function} _hsla-shade
+/// @requires {function} contrast
+/// @requires {function} to-opaque
+/// @returns {Map} - A map consisting of hsla color shades and thier respective contrast colors.
+@function shades(
+    $name,
+    $color,
+    $shades,
+    $surface: null
+) {
+    $result: ();
+
+    @each $variant in $shades {
+        $shade: shade($name, $color, $variant, $surface);
+        $result: map.merge(
+            $result,
+            (
+                $variant: map.get($shade, 'raw'),
+                #{$variant}-contrast: text-contrast(map.get($shade, 'raw')),
+                #{$variant}-hsl: map.get($shade, 'hsl'),
+            )
+        );
+    }
+
+    @return $result;
+}
+
+/// Generates a color shade for a given base colors.
+/// @access private
+/// @group Palettes
+/// @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).
+/// @returns {Map} - A map containing a list of HSL values and a raw color value.
+@function shade(
+    $name,
+    $color,
+    $shade,
+    $surface: null,
+) {
+    $h: var(--ig-#{$name}-h);
+    $s: var(--ig-#{$name}-s);
+    $l: var(--ig-#{$name}-l);
+
+    @if $name == gray {
+        $lum: luminance($surface);
+        $color: if($color, $color, if($lum > .5, #000, #fff));
+        $lmap: map.get(multipliers.$grayscale, 'l');
+        $len: list.length($lmap);
+        $i: list.index(map.keys($lmap), $shade);
+        $l: list.nth(map.values($lmap), if($lum > .5, $len - $i + 1, $i));
+
+        @return (
+            raw: hsl(
+                to-fixed(color.hue($color)),
+                to-fixed(color.saturation($color)),
+                $l
+            ),
+            hsl: #{$h, $s, $l}
+        );
+    } @else {
+        $sx: map.get(multipliers.$color, 's', $shade);
+        $lx: map.get(multipliers.$color, 'l', $shade);
+
+        @return (
+            raw: hsl(
+                to-fixed(color.hue($color)),
+                to-fixed(color.saturation($color) * $sx),
+                to-fixed(color.lightness($color) * $lx)
+            ),
+            hsl: #{$h, calc(#{$s} * #{$sx}), calc(#{$l} * #{$lx})}
+        );
+    }
+}
+
+/// 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 {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);
+    $a: var(--ig-#{$color}-a);
+    $s: #{var(--ig-#{$color}-#{$variant})};
+    $contrast: if(
+        meta.type-of($variant) == string,
+        string.index($variant, 'contrast'),
+        false
+    );
+    $meta: if($palette, map.get($palette, '_meta'), null);
+
+    @if not($c) {
+        @error 'The passed color #{$color} is not valid.';
+    }
+
+    @if not($palette) or not($meta) {
+        @return if(
+            $contrast,
+            $s,
+            hsla($s, if($opacity, $opacity, $a)),
+        );
+    }
+
+    @return rgba(map.get($c, $variant), $alpha: if($opacity, $opacity, 1));
+}
+
+/// 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.
+/// @param {Number | String} $variant [500] - The target color shade from the color palette.
+/// @requires 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);
+}
+
+/// Returns a contrast color for a passed color.
+/// @access public
+/// @group Color
+/// @param {Color} $background - The background color used to return a contrast/forground color for.
+/// @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.
+/// @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
+@function text-contrast(
+    $background,
+    $foreground: white,
+    $contrast: 'AAA'
+) {
+    @if meta.type-of($foreground) != 'list' and meta.type-of($background) != 'color' {
+        @return $background;
+    }
+
+    $level: map.get(
+        (
+            'a': 3,
+            'aa': 4.5,
+            'aaa': 7
+        ),
+        string.to-lower-case($contrast)
+    );
+
+    @if not($level) {
+        @error "$contrast must be 'A', 'AA', or 'AAA'";
+    }
+
+    $candidates: ();
+
+    @each $color in $foreground {
+        @if meta.type-of($color) != 'color' {
+            @return $background;
+        }
+
+        $candidates: list.append($candidates, contrast($background, $color));
+    }
+
+    $foreground: list.nth($foreground, list.index($candidates, math.max($candidates...)));
+
+    @if contrast($background, $foreground) >= $level {
+        @return $foreground;
+    } @else {
+        $lightContrast: contrast($background, white);
+        $darkContrast: contrast($background, black);
+
+        @if $lightContrast > $darkContrast {
+            @return white;
+        } @else {
+            @return black;
+        }
+    }
+}
+
+/// Mixes two colors to produce an opaque color.
+/// @access public
+/// @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.
+@function to-opaque($color-1, $color-2: #fff) {
+    @if meta.type-of($color-1) == color and meta.type-of($color-2) == color {
+        $red: color.red($color-1);
+        $green: color.green($color-1);
+        $blue: color.blue($color-1);
+        $a: color.alpha($color-1);
+        $r: math.floor($a * $red + (1 - $a) * color.red($color-2));
+        $g: math.floor($a * $green + (1 - $a) * color.green($color-2));
+        $b: math.floor($a * $blue + (1 - $a) * color.blue($color-2));
+
+        @return rgb($r, $g, $b);
+    }
+
+    @return $color-1;
+}
+
+/// Retruns a comma separated list of hue, saturation, and lightness values for a given color.
+/// @access public
+/// @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%);
+/// @return {List} - This list of HSL values.
+@function to-hsl($color) {
+    @return (color.hue($color), color.saturation($color), color.lightness($color));
+}
+
+/// Calculates the contrast ratio between two colors.
+/// See https://www.w3.org/TR/WCAG20-TECHS/G17.html#G17-tests
+///
+/// @param {Color} $background - The background color.
+/// @param {Color} $foreground - The foreground color.
+/// @returns {Number} - The contrast ratio between the background and foreground colors.
+@function contrast($background, $foreground) {
+    $backLum: luminance($background) + .05;
+    $foreLum: luminance($foreground) + .05;
+
+    @return to-fixed(math.div(math.max($backLum, $foreLum), math.min($backLum, $foreLum)));
+}
+
+/// Calculates the luminance for a given color.
+/// See https://www.w3.org/TR/WCAG20-TECHS/G17.html#G17-tests.
+///
+/// @param {Color} $color - The color to calculate luminance for.
+@function luminance($color) {
+    @if meta.type-of($color) == 'color' {
+        $r: math.div(color.red($color), 255);
+        $g: math.div(color.green($color), 255);
+        $b: math.div(color.blue($color), 255);
+
+        @return .2126 * _lcv($r) + .7152 * _lcv($g) + .0722 * _lcv($b);
+    }
+
+    @return $color;
+}
+
+/// Calculates the linear channel value for a given sRGB color.
+/// @access private
+@function _lcv($value) {
+    /* stylelint-disable number-max-precision */
+    @return if(
+        $value < .03928,
+        math.div($value, 12.92),
+        math.pow(math.div($value + .055, 1.055), 2.4)
+    );
+}
+
+/// Returns a list of colors to be used as chart brushes.
+/// @access public
+/// @group Palettes
+/// @returns { List } - A list of colors to be used as chart brushes.
+@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/_index.scss

@@ -0,0 +1,6 @@
+@forward 'functions';
+@forward 'mixins';
+@forward 'types';
+@forward 'multipliers';
+@forward 'charts';
+@forward 'presets';

package/sass/color/_mixins.scss

@@ -0,0 +1,48 @@
+@use 'sass:map';
+@use 'sass:meta';
+@use 'sass:math';
+@use 'sass:color';
+@use 'sass:string';
+@use '../utils/meta' as *;
+
+/// Generates CSS variables for a given palette.
+/// @access public
+/// @group Palettes
+/// @param {Map} $palette [null] - 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);
+///
+@mixin palette($palette, $contrast: true) {
+    $scope: if(is-root(), ':root', '&');
+
+    #{$scope} {
+        @each $color, $shades in map.remove($palette, '_meta') {
+            @each $shade, $value in $shades {
+                $_base-shade: $shade == 500;
+                $_valid-color: meta.type-of($value == 'color');
+                $_other-shade: meta.type-of($shade) == 'string';
+                $_hsl: if($_other-shade, string.index($shade, 'hsl'), false);
+                $_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)};
+                }
+
+                @if $_hsl {
+                    $variant: string.slice($shade, 1, string.index($shade, '-hsl') - 1);
+
+                    --ig-#{meta.inspect($color)}-#{$variant}: #{$value};
+                }
+
+                @if $_contrast and $contrast {
+                    --ig-#{meta.inspect($color)}-#{$shade}: #{$value};
+                }
+            }
+        }
+    }
+}

package/sass/color/_multipliers.scss

@@ -0,0 +1,48 @@
+$color: (
+    s: (
+        50: 1.23,
+        100: .8,
+        200: .64,
+        300: .73,
+        400: .875,
+        500: 1,
+        600: 1.26,
+        700: 1.52,
+        800: 1.5,
+        900: 1.34,
+        'A100': 1.23,
+        'A200': 1.22,
+        'A400': 1.23,
+        'A700': 1.23
+    ),
+    l: (
+        50: 1.78,
+        100: 1.66,
+        200: 1.43,
+        300: 1.19,
+        400: 1.08,
+        500: 1,
+        600: .89,
+        700: .81,
+        800: .73,
+        900: .64,
+        'A100': 1.34,
+        'A200': 1.16,
+        'A400': .91,
+        'A700': .65
+    )
+);
+$grayscale: (
+    l: (
+        50: 13%,
+        100: 26%,
+        200: 38%,
+        300: 54%,
+        400: 62%,
+        500: 74%,
+        600: 88%,
+        700: 93%,
+        800: 96%,
+        900: 98%
+    )
+);

package/sass/color/_types.scss

@@ -0,0 +1,37 @@
+@use 'sass:map';
+
+$IGrayShades: (
+    50: '',
+    100: '',
+    200: '',
+    300: '',
+    400: '',
+    500: '',
+    600: '',
+    700: '',
+    800: '',
+    900: '',
+);
+$IColorShades: map.merge(
+    $IGrayShades,
+    (
+        'A100': '',
+        'A200': '',
+        'A400': '',
+        'A700': '',
+    )
+);
+$IPaletteColors: (
+    primary: $IColorShades,
+    secondary: $IColorShades,
+    gray: $IGrayShades,
+    surface: $IColorShades,
+    info: $IColorShades,
+    success: $IColorShades,
+    warn: $IColorShades,
+    error: $IColorShades,
+);
+$IPaletteMeta: (
+    variant: '',
+);
+$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'
+);