var-colors 1.0.0

package/scss/_functions.scss

@@ -0,0 +1,720 @@
+@use "sass:meta";
+@use "sass:math";
+@use "sass:list";
+@use "sass:map";
+@use "sass:string";
+@use "./_constants" as *;
+@use "./_maps" as *;
+
+// 1.Configuration validations
+@function get-valid-colors($colors) {
+  $valid-colors: ();
+  @if meta.type-of($colors) == "list" {
+    @each $key in $colors {
+      @if meta.type-of($key) == "string" {
+        @if list.index($preset-colors-keys, $key) {
+          $valid-colors: list.append($valid-colors, $key);
+        } @else {
+          @warn For preset colors, only keys from the list "#{$preset-colors-keys}" are allowed,
+          the color with the invalid key "#{$key}" was ignored;
+        }
+      } @else {
+        @warn The preset color key must be of type "string",
+        the key "#{$key}" has an invalid type "#{meta.type-of($key)}",
+        the color was ignored;
+      }
+    }
+  } @else {
+    @warn The value of the variable "$colors" must be of type "list",
+    value "#{$colors}" with invalid type "#{meta.type-of($colors)}" was ignored;
+  }
+  @return $valid-colors;
+}
+
+@function get-valid-levels($levels) {
+  $valid-levels: ();
+  @if meta.type-of($levels) == "list" {
+    $wrong-levels: ();
+    $wrong-type-levels: ();
+    @each $level in $levels {
+      @if meta.type-of($level) == "number" {
+        @if $level % 25 == 0 {
+          $valid-levels: list.append($valid-levels, $level);
+        } @else {
+          $wrong-levels: list.append($wrong-levels, $level);
+        }
+      } @else {
+        $wrong-type-levels: list.append($wrong-type-levels, $level);
+      }
+    }
+    @if list.length($wrong-type-levels) > 0 {
+      @warn The levels must be of type "number",
+        the levels "#{$wrong-type-levels}" with invalid types was ignored;
+    }
+    @if list.length($wrong-levels) > 0 {
+      @warn The levels must be a multiple of 25,
+        the levels "#{$wrong-levels}" with invalid values was ignored;
+    }
+  } @else {
+    @warn The value of "$levels" must be of type "list",
+    value "#{$levels}" with invalid type "#{meta.type-of($levels)}" was ignored;
+  }
+  @return $valid-levels;
+}
+
+@function get-valid-levels-step($levels-step, $levels) {
+  @if list.length($levels) == 0 {
+    @if meta.type-of($levels-step) == "number" {
+      @if not list.index($valid-levels-steps, $levels-step) {
+        @warn For "$levels-step" only values from the list "#{$valid-levels-steps}" are allowed,
+        the value "#{$levels-step}" was ignored;
+        $levels-step: 50;
+      }
+    } @else {
+      @warn The value of "$levels-step" must be of type "number",
+      value "#{$levels-step}" with invalid type "#{meta.type-of($levels-step)}" was ignored;
+      $levels-step: 50;
+    }
+  }
+  @return $levels-step;
+}
+
+@function get-valid-consistent-chroma($consistent-chroma) {
+  @if meta.type-of($consistent-chroma) != "bool" {
+    @warn The value of "$consistent-chroma" must be of type "bool",
+      value "#{$consistent-chroma}" with invalid type "#{meta.type-of($consistent-chroma)}" was ignored;
+    $consistent-chroma: false;
+  }
+  @return $consistent-chroma;
+}
+
+@function get-valid-gamut($gamut) {
+  @if meta.type-of($gamut) == "string" {
+    @if not list.index($valid-gamuts, $gamut) {
+      @warn For "$gamut" only values from the list "#{$valid-gamuts}" are allowed,
+      the value "#{$gamut}" was ignored;
+      $gamut: "srgb";
+    }
+  } @else {
+    @warn The value of "$gamut" must be of type "string",
+      value "#{$gamut}" with invalid type "#{meta.type-of($gamut)}" was ignored;
+    $gamut: "srgb";
+  }
+  @return $gamut;
+}
+
+@function get-valid-prefix($prefix) {
+  @if meta.type-of($prefix) != "string" and meta.type-of($prefix) != "null" {
+    @warn The value of "$prefix" must be of type "string" or "null",
+      value "#{$prefix}" with invalid type "#{meta.type-of($prefix)}" was ignored;
+    $prefix: null;
+  }
+  @return $prefix;
+}
+
+@function get-valid-root-rule($root-rule) {
+  @if meta.type-of($root-rule) != "bool" {
+    @warn The value of "$root-rule" must be of type "bool",
+      value "#{$root-rule}" with invalid type "#{meta.type-of($root-rule)}" was ignored;
+    $root-rule: false;
+  }
+  @return $root-rule;
+}
+
+// 2.Getting preset colors by the configuration
+@function get-preset-colors-by-keys($color-keys) {
+  $colors: ();
+  @each $key in $color-keys {
+    $value: map.get($preset-colors, $key);
+    $colors: map.merge(
+      $colors,
+      (
+        $key: $value,
+      )
+    );
+  }
+  @return $colors;
+}
+
+// 3.Creating a list of levels
+@function get-levels-by-config($levels, $levels-step) {
+  @if (not $levels or list.length($levels) == 0) and $levels-step {
+    $levels: ();
+    $palette-steps: calc(1000 / $levels-step - 1);
+    @for $i from 1 through $palette-steps {
+      $levels: list.append($levels, $i * $levels-step);
+    }
+  }
+  @return $levels;
+}
+
+// 4.Setting the max-chroma value for preset colors
+@function get-preset-colors-chroma($colors, $consistent-chroma, $gamut) {
+  $preset-colors-with-max-chroma: ();
+  @each $key, $color-data in $colors {
+    @if $consistent-chroma {
+      $color-data-without-max-chroma-lightness: map.remove(
+        $color-data,
+        "max-chroma-lightness"
+      );
+      $color-data: map.merge(
+        $color-data-without-max-chroma-lightness,
+        (
+          max-chroma: "consistent",
+        )
+      );
+    } @else {
+      $max-chroma: map.get($color-data, "max-chroma", $gamut);
+      $color-data: map.merge(
+        $color-data,
+        (
+          max-chroma: $max-chroma,
+        )
+      );
+    }
+    $preset-colors-with-max-chroma: map.merge(
+      $preset-colors-with-max-chroma,
+      (
+        $key: $color-data,
+      )
+    );
+  }
+  @return $preset-colors-with-max-chroma;
+}
+
+@function create-variable-hue($key, $color-data, $prefix) {
+  @if $prefix {
+    $color-data: map.merge(
+      $color-data,
+      (
+        hue: var(--#{$prefix}-#{$color-key}-hue),
+      )
+    );
+  } @else {
+    $color-data: map.merge(
+      $color-data,
+      (
+        hue: var(--#{$color-key}-hue),
+      )
+    );
+  }
+}
+
+@function get-level-by-lightness($darkness-levels, $lightness) {
+  $darkness-level: 0;
+  @each $level, $color-data in $darkness-levels {
+    $min-lightness: map.get($color-data, "min-lightness");
+    $max-lightness: map.get($color-data, "max-lightness");
+    @if $lightness >= $min-lightness and $lightness < $max-lightness {
+      $darkness-level: $level;
+    }
+  }
+  @return $darkness-level;
+}
+
+@function get-color-max-chroma-level($color-data, $gamut) {
+  $max-chroma-lightness-data: map.get($color-data, max-chroma-lightness);
+  $max-chroma-lightness: null;
+  @if meta.type-of($max-chroma-lightness-data) == "map" {
+    $max-chroma-lightness: map.get($max-chroma-lightness-data, $gamut);
+  } @else if meta.type-of($max-chroma-lightness-data) == "number" {
+    $max-chroma-lightness: $max-chroma-lightness-data;
+  }
+  $max-chroma-level: get-level-by-lightness(
+    $darkness-levels,
+    $max-chroma-lightness
+  );
+  @return $max-chroma-level;
+}
+
+@function get-lightness-by-level($level) {
+  @return map.get($darkness-levels, $level, "lightness");
+}
+
+@function get-consistent-chroma-by-level($level) {
+  @return map.get($darkness-levels, $level, "consistent-chroma");
+}
+
+@function get-regular-chroma-by-level($level, $max-chroma-level, $max-chroma) {
+  $chroma: null;
+  @if $level == $max-chroma-level {
+    $chroma: $max-chroma;
+  } @else if $level < $max-chroma-level {
+    $chroma: math.div($level, $max-chroma-level) * $max-chroma;
+  } @else if $level > $max-chroma-level {
+    $chroma: math.div(1000 - $level, 1000 - $max-chroma-level) * $max-chroma;
+  }
+  @return $chroma;
+}
+
+@function get-shade-chroma($color-data, $level, $max-chroma-level) {
+  $hue: map.get($color-data, "hue");
+  $max-chroma: map.get($color-data, "max-chroma");
+  $chroma: null;
+  @if $hue == none {
+    $chroma: 0;
+  } @else if $max-chroma == "consistent" {
+    $chroma: get-consistent-chroma-by-level($level);
+  } @else if $max-chroma and meta.type-of($max-chroma) == number {
+    $chroma: get-regular-chroma-by-level(
+      $level,
+      $max-chroma-level,
+      $max-chroma
+    );
+  } @else {
+    $chroma: get-regular-chroma-by-level(
+      $level,
+      $max-chroma-level,
+      $default-max-chroma
+    );
+  }
+  @return $chroma;
+}
+
+@function get-leading-zeros-level-key($level) {
+  $leading-zeros-level: $level;
+  @if ($level < 100) {
+    $leading-zeros-level: "0" + $leading-zeros-level;
+  }
+  @return $leading-zeros-level;
+}
+
+@function round-to($number, $decimals: 0) {
+  $multiplier: math.pow(10, $decimals);
+  @return math.div(math.round($number * $multiplier), $multiplier);
+}
+
+@function get-oklch-value($lightness, $chroma, $hue) {
+  $oklch-value: "oklch(" + round-to($lightness, 4) + " " +
+    round-to($chroma, 4) + " " + $hue + ")";
+  @return $oklch-value;
+}
+
+@function create-palette-from-color(
+  $color-key,
+  $color-data,
+  $levels,
+  $gamut,
+  $prefix
+) {
+  $hue: map.get($color-data, "hue");
+  $max-chroma: map.get($color-data, "max-chroma");
+  $max-chroma-level: null;
+  $max-chroma-lightness: null;
+  @if meta.type-of($hue) == number and map.get($color-data, "var-hue") == true {
+    $color-data: create-variable-hue($color-key, $color-data, $prefix);
+  }
+  @if $max-chroma != "consistent" {
+    $max-chroma-level: get-color-max-chroma-level($color-data, $gamut);
+  }
+  $colors-palette: ();
+  @each $level in $levels {
+    $color-name: $color-key + "-" + get-leading-zeros-level-key($level);
+    $lightness: get-lightness-by-level($level);
+    $chroma: get-shade-chroma($color-data, $level, $max-chroma-level);
+    $color: (
+      $color-name: get-oklch-value($lightness, $chroma, $hue),
+    );
+    $colors-palette: map.merge($colors-palette, $color);
+  }
+  @return $colors-palette;
+}
+
+// 5.Generating a palette of shades of preset colors
+@function get-preset-colors-palette($colors, $levels, $gamut, $prefix) {
+  $preset-colors-palette: ();
+  @each $color-key, $color-data in $colors {
+    $current-color-palette: create-palette-from-color(
+      $color-key,
+      $color-data,
+      $levels,
+      $gamut,
+      $prefix
+    );
+    $preset-colors-palette: map.merge(
+      $preset-colors-palette,
+      $current-color-palette
+    );
+  }
+  @return $preset-colors-palette;
+}
+
+@function validate-hue($color-key, $color-data) {
+  $hue: map.get($color-data, "hue");
+  $var-hue: map.get($color-data, "var-hue");
+  @if list.index($preset-colors-keys, $color-key + "") {
+    @warn Using names from the list of preset colors 
+      "#{$preset-colors-keys}"  to name the custom color
+      "#{$color-key}" is invalid, the custom color "#{$color-key}" has been ignored;
+    @return false;
+  } @else {
+    @if meta.type-of($hue) == number {
+      @return true;
+    } @else if meta.type-of($hue) == string {
+      @if list.index($preset-colors-keys, $hue) or $hue == "none" {
+        @return true;
+      } @else if string.index($hue, "var(") and string.index($hue, ")") {
+        @if $var-hue == true {
+          @return true;
+        } @else {
+          @warn Using the "#{$hue}" value for the "hue" property
+          of the custom "#{$color-key}" color without the "var-hue: true" flag is invalid,
+          the custom "#{$color-key}" color was ignored;
+          @return false;
+        }
+      } @else {
+        @warn Using the $hue value for the "hue" property of the 
+          custom "#{$color-key}" color is invalid, the custom "#{$color-key}" color was ignored;
+        @return false;
+      }
+    } @else if meta.type-of($hue) == calculation {
+      @if $var-hue == true {
+        @return true;
+      } @else {
+        @warn Using the "#{$hue}" value for the "hue" property
+        of the custom "#{$color-key}" color without the "var-hue: true" flag is invalid,
+        the custom "#{$color-key}" color was ignored;
+        @return false;
+      }
+    } @else {
+      @warn The absence of the "hue" property \or the use of the "null" value for
+        the "hue" property of the custom color "#{$color-key}" is invalid, the custom color "#{$color-key}" was ignored;
+      @return false;
+    }
+  }
+}
+
+// 6.Filtering custom colors by valid hue
+@function filter-colors-by-valid-hue($custom-colors) {
+  $valid-custom-colors: ();
+  @each $key, $value in $custom-colors {
+    @if validate-hue($key, $value) {
+      $valid-custom-colors: map.merge(
+        $valid-custom-colors,
+        (
+          $key: $value,
+        )
+      );
+    }
+  }
+  @return $valid-custom-colors;
+}
+
+// 7.Converting string custom colors hue values matching the names of preset colors to numeric values
+@function convert-custom-colors-string-hues-to-numbers($custom-colors) {
+  $colors: ();
+  @each $key, $value in $custom-colors {
+    $hue: map.get($value, "hue");
+    @if meta.type-of($hue) == string and list.index($preset-colors-keys, $hue) {
+      $hue-number: map.get($preset-colors, $hue, "hue");
+      $value: map.merge(
+        $value,
+        (
+          hue: $hue-number,
+        )
+      );
+    }
+    $colors: map.merge(
+      $colors,
+      (
+        $key: $value,
+      )
+    );
+  }
+  @return $colors;
+}
+
+@function get-preset-color-data-by-color-key($color-key) {
+  @return map.get($preset-colors, $color-key);
+}
+
+@function get-preset-color-data-by-hue($hue) {
+  @if meta.type-of($hue) == number {
+    $hue: $hue % 360;
+  } @else if $hue == "none" {
+    @return get-preset-color-data-by-color-key("grey");
+  }
+  $preset-color-index: list.index($preset-colors-hues, $hue);
+  @if $preset-color-index {
+    $color-key: list.nth($preset-colors-keys, $preset-color-index);
+    @return map.get($preset-colors, $color-key);
+  }
+  @return null;
+}
+
+// 8.Setting the max-chroma value for custom colors
+@function get-custom-color-chroma($custom-colors, $gamut) {
+  $colors: ();
+  @each $key, $value in $custom-colors {
+    $hue: map.get($value, "hue");
+    @if meta.type-of($hue) == "number" {
+      $hue: $hue % 360;
+    }
+    $max-chroma: map.get($value, "max-chroma");
+    @if $max-chroma == "consistent" {
+      $no-lightness-value: map.remove($value, "max-chroma-lightness");
+      $value: map.merge(
+        $no-lightness-value,
+        (
+          max-chroma: "consistent",
+        )
+      );
+    } @else if list.index($preset-colors-hues, $hue) and not $max-chroma {
+      $preset-color: get-preset-color-data-by-hue($hue);
+      $max-chroma: map.get($preset-color, "max-chroma", $gamut);
+      $value: map.merge(
+        $value,
+        (
+          max-chroma: $max-chroma,
+        )
+      );
+    } @else if $hue == "none" {
+      $no-lightness-value: map.remove($value, "max-chroma-lightness");
+      $value: map.merge(
+        $no-lightness-value,
+        (
+          max-chroma: 0,
+        )
+      );
+    } @else if $max-chroma and meta.type-of($max-chroma) == number {
+      @if $max-chroma >= 0 and $max-chroma <= 0.4 {
+        $value: $value;
+      } @else if $max-chroma < 0 {
+        @warn 'Using the negative value of the "max-chroma" property of the custom color "#{$key}" does not make sense, the value has been changed to "0"';
+        $value: map.merge(
+          $value,
+          (
+            max-chroma: 0,
+          )
+        );
+      } @else {
+        @warn 'Using a value greater than 0.4 of the "max-chroma" property of the custom color "#{$key}" can lead to unexpected results';
+        $value: $value;
+      }
+    } @else {
+      @if $max-chroma {
+        @warn 'Non-negative numeric values should be used for the "max-chroma" property of the custom color, the value "#{$max-chroma}" of the color "#{$key}" was ignored';
+      }
+      $value: map.merge(
+        $value,
+        (
+          max-chroma: $default-max-chroma,
+        )
+      );
+    }
+    $colors: map.merge(
+      $colors,
+      (
+        $key: $value,
+      )
+    );
+  }
+  @return $colors;
+}
+
+// 9.Adoption of max-chroma-lightness values to the range from 0 to 1
+@function adopt-max-chroma-lightness($color-key, $color-data) {
+  $max-chroma-lightness: map.get($color-data, "max-chroma-lightness");
+  @if meta.type-of($max-chroma-lightness) == number {
+    @if $max-chroma-lightness < 0 {
+      @warn 'The use of negative values for the "max-chroma-lightness" property is not allowed, the value "#{$max-chroma-lightness}" of the color "#{$color-key}" has been converted to the value "0"';
+      $color-data: map.merge(
+        $color-data,
+        (
+          max-chroma-lightness: 0,
+        )
+      );
+    } @else if $max-chroma-lightness > 1 {
+      @warn 'Using values greater than 1 for the "max-chroma-lightness" property is not allowed, the value "#{$max-chroma-lightness}" of the custom color "#{$color-key}" has been converted to the value "1"';
+      $color-data: map.merge(
+        $color-data,
+        (
+          max-chroma-lightness: 1,
+        )
+      );
+    }
+  } @else if $max-chroma-lightness {
+    $color-data: map.remove($color-data, "max-chroma-lightness");
+    @warn 'For the "max-chroma-lightness" property of a custom color values from 0 to 1 should be used, the value "#{$max-chroma-lightness}" of the color "#{$color-key}" was ignored';
+  }
+  $color: (
+    $color-key: $color-data,
+  );
+  @return $color;
+}
+
+@function validate-custom-colors-max-chroma-lightness($custom-colors) {
+  $colors: ();
+  @each $key, $value in $custom-colors {
+    $adopted-color: adopt-max-chroma-lightness($key, $value);
+    $colors: map.merge($colors, $adopted-color);
+  }
+  @return $colors;
+}
+
+// 10.Setting the max-chroma-lightness value for custom colors
+@function get-custom-colors-max-chroma-lightness($custom-colors, $gamut) {
+  $colors: ();
+  @each $key, $value in $custom-colors {
+    $hue: map.get($value, "hue");
+    $max-chroma: map.get($value, "max-chroma");
+    $max-chroma-lightness: map.get($value, "max-chroma-lightness");
+    @if $max-chroma != "consistent" and not $max-chroma-lightness {
+      $preset-color-data: null;
+      @if meta.type-of($hue) == number {
+        $preset-color-data: get-preset-color-data-by-hue($hue % 360);
+      }
+      @if meta.type-of($hue) == string {
+        @if $hue == none {
+          $preset-color-data: get-preset-color-data-by-color-key("grey");
+        } @else {
+          $preset-color-data: get-preset-color-data-by-color-key($hue);
+        }
+      }
+      @if $preset-color-data {
+        $preset-max-chroma-lightness: map.get(
+          $preset-color-data,
+          "max-chroma-lightness",
+          $gamut
+        );
+        $value: map.merge(
+          $value,
+          (
+            max-chroma-lightness: $preset-max-chroma-lightness,
+          )
+        );
+      } @else {
+        $value: map.merge(
+          $value,
+          (
+            max-chroma-lightness: $default-max-chroma-lightness,
+          )
+        );
+      }
+    }
+    $colors: map.merge(
+      $colors,
+      (
+        $key: $value,
+      )
+    );
+  }
+  @return $colors;
+}
+
+// 11.Getting a list of dynamic hues
+@function get-dynamic-var-hues($custom-colors, $prefix) {
+  $hues: ();
+  @each $color-name, $color-data in $custom-colors {
+    @if map.get($color-data, "var-hue") == true {
+      $hues: map.merge(
+        $hues,
+        (#{$color-name}-hue: map.get($color-data, "hue"))
+      );
+    }
+  }
+  @return $hues;
+}
+
+// 12.Creating a list of dynamic hue values
+@function get-custom-colors-variable-hue($custom-colors, $prefix) {
+  $colors: ();
+  @each $color-name, $color-data in $custom-colors {
+    @if map.get($color-data, "var-hue") == true {
+      @if $prefix {
+        $color-data: map.merge(
+          $color-data,
+          (
+            hue: var(--#{$prefix}-#{$color-name}-hue),
+          )
+        );
+      } @else {
+        $color-data: map.merge(
+          $color-data,
+          (
+            hue: var(--#{$color-name}-hue),
+          )
+        );
+      }
+    } @else if
+      map.has-key($color-data, "var-hue") and
+      map.get($color-data, "var-hue") !=
+      false
+    {
+      @warn 'The color property "var-hue" can only take a boolean value, the value of “#{map.get($color-data, 'var-hue') or 'null'}" for the color "#{$color-name}" was ignored';
+      $color-data: map.remove($color-data, "var-hue");
+    }
+    $colors: map.merge(
+      $colors,
+      (
+        $color-name: $color-data,
+      )
+    );
+  }
+  @return $colors;
+}
+
+// 13.Generating a palette of shades of custom colors
+@function get-custom-colors-palette($custom-colors, $levels, $gamut, $prefix) {
+  $palette: ();
+  @each $color-key, $color-data in $custom-colors {
+    $current-color-palette: create-palette-from-color(
+      $color-key,
+      $color-data,
+      $levels,
+      $gamut,
+      $prefix
+    );
+    $palette: map.merge($palette, $current-color-palette);
+  }
+  @return $palette;
+}
+
+// 16.Report on completed work
+@function get-report(
+  $custom-hues-count,
+  $custom-shades-count,
+  $preset-shades-count,
+  $root-rule
+) {
+  $report-text: "The work of var-colors is completed,";
+  @if $custom-hues-count ==
+    0 and
+    $custom-shades-count ==
+    0 and
+    $preset-shades-count ==
+    0
+  {
+    $report-text: $report-text +
+      " but no custom properties have been created. Check if the configuration is correct";
+  } @else {
+    $report-text: $report-text + " created";
+    @if $custom-hues-count > 0 {
+      $report-text: $report-text + " " + $custom-hues-count + " variable hue";
+      @if not $root-rule {
+        $report-text: $report-text + ' in "$var-hues" scss-variable';
+      }
+      $report-text: $report-text + ",";
+    }
+    @if $custom-shades-count > 0 {
+      $report-text: $report-text +
+        " " +
+        $custom-shades-count +
+        " shades of custom colors,";
+    }
+    @if $preset-shades-count > 0 {
+      $report-text: $report-text +
+        " " +
+        $preset-shades-count +
+        " shades of preset colors,";
+    }
+    $report-text: string.slice($report-text, 1, -2);
+    @if $root-rule {
+      $report-text: $report-text + " in root-rule";
+    } @else {
+      $report-text: $report-text + ' in "$palette" scss-variable';
+    }
+  }
+
+  @return $report-text;
+}