@guebbit/css-toolkit 1.1.1 → 1.1.3

package/src/functions/_colors.scss

@@ -0,0 +1,109 @@
+@use "sass:color" as color;
+@use "sass:math" as math;
+@use "sass:string" as string;
+
+/**
+ * Return opaque color
+ * color-opaque(#fff, rgba(0, 0, 0, .5)) => #808080
+ * function credited to https://getbootstrap.com/
+ */
+@function color-opaque($background, $foreground) {
+  @return color.mix(rgba($foreground, 1), $background, opacity($foreground) * 100%, $method: rgb);
+}
+
+/**
+ * Shade the color if the weight is positive, else tint it
+ * function credited to https://getbootstrap.com/
+ */
+@function color-shift($color, $weight) {
+  @return if($weight > 0, color.scale($color, $lightness: $weight), color.scale($color, $lightness: -$weight));
+}
+
+
+/**
+ * Compares contrast of a given color to the light/dark arguments and returns whichever is most "contrasty"
+ */
+@function color-contrast($color: #fff, $dark: #000, $light: #fff) {
+  @if type-of($color) != color or $color == transparent {
+    @return inherit;
+  }
+  $color-brightness: color-brightness($color);
+  $light-text-brightness: color-brightness($light);
+  $dark-text-brightness: color-brightness($dark);
+
+  @return if(abs($color-brightness - $light-text-brightness) > abs($color-brightness - $dark-text-brightness), $light, $dark);
+}
+
+
+
+// Return WCAG2.1 relative luminance
+// See https://www.w3.org/TR/WCAG/#dfn-relative-luminance
+// See https://en.wikipedia.org/wiki/Relative_luminance
+// Gives %, less than 50 darker is better, less than 50, lighter.
+@function color-brightness($color) {
+  // fallback
+  @if $color == transparent or type-of($color) != color {
+    @return 100;
+  }
+  @return math.div((
+          (color.channel($color, "red", $space: rgb) * .299) +
+          (color.channel($color, "green", $space: rgb) * .587) +
+          (color.channel($color, "blue", $space: rgb) * .114)
+  ), 255 * 100%);
+}
+
+/**
+ * NEW numeric annotation
+ * Hex to RGB (only numbers, transparentize would add rgba(*))
+ * $color
+ * $alpha:
+ *    - 0: never 4° digit
+ *    - 1: always 4° digit
+ *    - 2: 4° digit only when needed
+ * $classic: false = new number annotation
+ */
+@function extract-colors($color: #fff, $mode: 2, $classic: false){
+  // colors only
+  @if $color == transparent or type-of($color) != color {
+    @return $color;
+  }
+  // new annotation
+  $delimiter: " ";
+  $delimiter-alpha: " / ";
+  // old annotation
+  @if $classic{
+    $delimiter: ", ";
+    $delimiter-alpha: ", ";
+  }
+  $alpha: alpha($color);
+  @if $mode == 1 or ($mode == 2 and $alpha == 1) {
+    @return color.channel($color, "red", $space: rgb) +
+        $delimiter + color.channel($color, "green", $space: rgb) +
+        $delimiter + color.channel($color, "blue", $space: rgb);
+  }
+  // Regular RGBA compliant result ("number" notation)
+  @return color.channel($color, "red", $space: rgb) +
+        $delimiter + color.channel($color, "green", $space: rgb) +
+        $delimiter + color.channel($color, "blue", $space: rgb) +
+        $delimiter-alpha + color.channel($color, "alpha"); // * 100%
+}
+
+/**
+ * Create default collection
+ */
+// TODO CHECK
+@function create-collection($color){
+  $list: (
+          "100": color.scale($color, $lightness: 80%),
+          "200": color.scale($color, $lightness: 60%),
+          "300": color.scale($color, $lightness: 40%),
+          "400": color.scale($color, $lightness: 20%),
+          "500": $color,
+          "600": color.scale($color, $lightness: -20%),
+          "700": color.scale($color, $lightness: -40%),
+          "800": color.scale($color, $lightness: -60%),
+          "900": color.scale($color, $lightness: -80%)
+  );
+
+  @return $list
+}

package/src/functions/_helpers.scss

@@ -0,0 +1,42 @@
+/**
+ * Giving a list of variables and values,
+ * from start to end, try all the values until a non-null is found
+ */
+@function no-null-var($list: ()){
+  @each $value in $list {
+    // stylelint-disable-next-line scss/at-if-no-null
+    @if $value != null and $value != undefined {
+      @return $value;
+    }
+  }
+  @return null;
+}
+
+/**
+ * If the color is the checked one, return inherit
+ */
+@function no-target-var($check: transparent, $color: transparent){
+  @if $color == $check {
+    @return inherit;
+  }
+  @return $color;
+}
+
+
+/**
+ * This function is to be used to return nested key values within a nested map
+ * @parameter {Variable} $map [null] - pass in map to be evaluated
+ * @parameter {Variable} $keys [null] - pass in keys to be evaluated
+ */
+//   $map: (
+//     'size': (
+//       'sml': 10px
+//     )
+//   );
+//   $var: map-deep-get($map, 'size', 'sml'); // => 10px
+@function map-deep-get($map, $keys...) {
+  @each $key in $keys {
+    $map: map-get($map, $key);
+  }
+  @return $map;
+}

package/src/functions/_strings.scss

@@ -0,0 +1,31 @@
+/**
+  Split string into lists
+ */
+@function string-split($string, $separator: "-") {
+  // empty array/list
+  $split-arr: ();
+  // first index of separator in string
+  $index : str-index($string, $separator);
+  // loop through string
+  @while $index != null {
+    // get the substring from the first character to the separator
+    $item: str-slice($string, 1, $index - 1);
+    // push item to array
+    $split-arr: append($split-arr, $item);
+    // remove item and separator from string
+    $string: str-slice($string, $index + 1);
+    // find new index of separator
+    $index : str-index($string, $separator);
+  }
+  // add the remaining string to list (the last item)
+  $split-arr: append($split-arr, $string);
+
+  @return $split-arr;
+}
+
+/**
+  Check if $string ends with $find
+ */
+@function string-ends-with($string, $find) {
+  @return (str-length($string) >= str-length($find)) and (str-slice($string, (str-length($string) - str-length($find) + 1)) == $find);
+}

package/src/index.scss

@@ -0,0 +1,13 @@
+@forward "./colors";
+
+@forward "./functions/colors";
+@forward "./functions/helpers";
+@forward "./functions/strings";
+
+@forward "./mixins/build-aspect-ratio";
+@forward "./mixins/build-compatibility";
+@forward "./mixins/build-scrollbar";
+@forward "./mixins/create-colors";
+@forward "./mixins/create-instructions";
+@forward "./mixins/create-helper-margin";
+@forward "./mixins/create-helper-padding";

package/src/mixins/_build-aspect-ratio.scss

@@ -0,0 +1,37 @@
+@use "../functions/strings" as guebbit;
+
+/**
+ * Use in the parent\container, to be coupled with {build-aspect-ratio-anchor}
+ */
+@mixin build-aspect-ratio-container($ratio: 100%){
+  position: relative;
+  // aspect-ratio: #{$height} / #{$width};
+
+  &::before{
+    content: "";
+    display: block;
+    padding-top: #{$ratio};
+  }
+}
+
+/**
+ * Use in the child that "gives" form to the parent that has the respective {build-aspect-ratio-container}
+ */
+@mixin build-aspect-ratio-anchor{
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+}
+
+/**
+ *  aspect ratio shortcut
+ */
+@mixin build-aspect-ratio($ratio: 100%){
+  @include build-aspect-ratio-container($ratio);
+
+  & > * {
+    @include build-aspect-ratio-anchor;
+  }
+}

package/src/mixins/_build-compatibility.scss

@@ -0,0 +1,28 @@
+/**
+*	Compatibility mode for browsers
+*	@param string $browser: target browser
+*	@content
+**/
+@mixin build-compatibility($browser) {
+  // INTERNET EXPLORER
+  @if $browser == "ie" {
+    @media all and (-ms-high-contrast: none), (-ms-high-contrast: active) {
+      @content;
+    }
+  }
+  // MICROSOFT EDGE
+  @if $browser == "edge" {
+    @supports (-ms-ime-align:auto) {
+      @content;
+    }
+  }
+  // FIREFOX
+  @if $browser == "firefox" {
+    @supports (-moz-appearance:none) {
+      @content;
+    }
+  }
+
+  // OPERA TODO
+  // SAFARI TODO
+}

package/src/mixins/_build-scrollbar.scss

@@ -0,0 +1,32 @@
+/**
+ *	Builder - scrollbars of element
+ *	@param string $color
+ *	@param pixels $size
+ *	@param $background: if false, has default lighten 40%
+ */
+@mixin build-scrollbar($size: "4px", $color: "#fff", $bg: "auto", $radius: "10px") {
+  $fallback-color: #fff;
+  $fallback-bg: transparent;
+
+  @if $bg == "auto" {
+    $bg: $fallback-bg;
+  }
+
+  &::-webkit-scrollbar {
+    width: $size;
+    height: $size;
+    background-color: $fallback-bg;
+    background-color: $bg;
+  }
+
+  &::-webkit-scrollbar-thumb {
+    border-radius: $radius;
+    background-color: $fallback-color;
+    background-color: $color;
+  }
+
+  &::-webkit-scrollbar-corner {
+    background-color: $fallback-bg;
+    background-color: $bg;
+  }
+}

package/src/mixins/_create-colors.scss

@@ -0,0 +1,119 @@
+@use "sass:list";
+@use "sass:string";
+@use "../functions/colors" as color-functions;
+
+/**
+ *  Create all the needed classes for the requested colors
+ *  $color-list     - list of colors (like $colors-collection: ("branch": ( "leaf: $color" )))
+ *  $branch-list:   - when filled: becomes a whitelist (aka: include only listed brands)
+ *  $feature-list:  - when filled: becomes a whitelist. May become cumbersome and many are not needed. Use with care.
+ *    - root
+ *    - on-root (color's "best contrast" partner color)
+ *    - color
+ *    - background
+ *    - border
+ *    - pseudo (bg only, color very rarely used)
+ *    - hover
+ *    $prefix: prefix that applies to classes
+ */
+@mixin create-colors($color-list: (), $branch-list: (), $feature-list: (), $prefix: "") {
+  // for every branch
+  @each $branch-name, $branch in $color-list {
+    // check that there is no $branch-list or, if present, it's correctly whitelisted
+    @if list.length($branch-list) < 1 or list.index($branch-list, $branch-name) {
+
+      // for every leaf
+      @each $sname, $scolor in $branch {
+
+        @if not list.index($branch-name, "advanced"){
+          @if list.length($feature-list) < 1 or list.index($feature-list, "color") {
+            .#{$prefix}#{$branch-name}-#{$sname}-text {
+              color: $scolor !important;
+            }
+          }
+          @if list.length($feature-list) < 1 or list.index($feature-list, "border") {
+            .#{$prefix}#{$branch-name}-#{$sname}-border {
+              border-color: $scolor !important;
+            }
+          }
+        }
+
+        @if list.length($feature-list) < 1 or list.index($feature-list, "background") {
+          .#{$prefix}#{$branch-name}-#{$sname}-bg {
+            background: $scolor !important;
+          }
+        }
+
+        @if list.length($feature-list) < 1 or list.index($feature-list, "pseudo") {
+          .#{$prefix}#{$branch-name}-#{$sname}-pseudo-bg {
+            &::after,
+            &::before {
+              background: $scolor !important;
+            }
+          }
+        }
+
+        @if list.length($feature-list) < 1 or list.index($feature-list, "hover"){
+
+          @if not list.index($branch-name, "advanced"){
+            @if list.length($feature-list) < 1 or list.index($feature-list, "color"){
+              .#{$prefix}#{$branch-name}-#{$sname}-hover-text {
+                &:hover {
+                  color: $scolor !important;
+                }
+              }
+            }
+            @if list.length($feature-list) < 1 or list.index($feature-list, "border"){
+              .#{$prefix}#{$branch-name}-#{$sname}-hover-border {
+                &:hover {
+                  border-color: $scolor !important;
+                }
+              }
+            }
+          }
+
+          @if list.length($feature-list) < 1 or list.index($feature-list, "background") {
+            .#{$prefix}#{$branch-name}-#{$sname}-hover-bg {
+              &:hover {
+                background: $scolor !important;
+              }
+            }
+          }
+
+          @if list.length($feature-list) < 1 or list.index($feature-list, "pseudo") {
+            .#{$prefix}#{$branch-name}-#{$sname}-hover-pseudo-bg {
+              &:hover{
+                &::after,
+                &::before {
+                  background: $scolor !important;
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * CSS VARS on root (they will be translated in "RGB" instead of "HEX"
+   */
+  :root{
+    @if list.length($feature-list) < 1 or list.index($feature-list, "root"){
+      @each $branch-name, $branch in $color-list {
+        @each $sname, $scolor in $branch {
+          --#{$prefix}#{$branch-name}-#{$sname}: #{color-functions.extract-colors($scolor)};
+        }
+      }
+    }
+    @if list.length($feature-list) < 1 or list.index($feature-list, "on-root"){
+      @each $branch-name, $branch in $color-list {
+        @each $sname, $scolor in $branch {
+          // @if type-of($scolor) == color {
+          --#{$prefix}on-#{$branch-name}-#{$sname}: #{color-functions.extract-colors(color-functions.color-contrast($scolor))};
+          // _}
+        }
+      }
+    }
+  }
+}

package/src/mixins/_create-helper-margin.scss

@@ -0,0 +1,39 @@
+/**
+ *
+ * t - applies the spacing for margin-top
+ * b - applies the spacing for margin-bottom
+ * l - applies the spacing for margin-left
+ * r - applies the spacing for margin-right
+ * x - applies the spacing for both *-left and *-right
+ * y - applies the spacing for both *-top and *-bottom
+ * a - applies the spacing for the property in all directions
+ *
+ * @param {Array<name,value>[]} measure-list - postfix name and value
+ */
+@mixin create-helper-margin($measure-list: (), $important: false, $prefix: "") {
+  @each $name, $val in $measure-list {
+    .#{$prefix}mt-#{$name} {
+      margin-top: #{$val} #{if($important == true, "!important", "")};
+    }
+    .#{$prefix}mb-#{$name} {
+      margin-bottom: #{$val} #{if($important == true, "!important", "")};
+    }
+    .#{$prefix}ml-#{$name} {
+      margin-left: #{$val} #{if($important == true, "!important", "")};
+    }
+    .#{$prefix}mr-#{$name} {
+      margin-right: #{$val} #{if($important == true, "!important", "")};
+    }
+    .#{$prefix}mx-#{$name} {
+      margin-right: #{$val} #{if($important == true, "!important", "")};
+      margin-left: #{$val} #{if($important == true, "!important", "")};
+    }
+    .#{$prefix}my-#{$name} {
+      margin-top: #{$val} #{if($important == true, "!important", "")};
+      margin-bottom: #{$val} #{if($important == true, "!important", "")};
+    }
+    .#{$prefix}ma-#{$name} {
+      margin: #{$val} #{if($important == true, "!important", "")};
+    }
+  }
+}

package/src/mixins/_create-helper-padding.scss

@@ -0,0 +1,40 @@
+/**
+ *
+ * t - applies the spacing for padding-top
+ * b - applies the spacing for padding-bottom
+ * l - applies the spacing for padding-left
+ * r - applies the spacing for padding-right
+ * x - applies the spacing for both *-left and *-right
+ * y - applies the spacing for both *-top and *-bottom
+ * a - applies the spacing for the property in all directions
+
+ * @param {Array<name,value>[]} measure-list - postfix name and value
+ */
+@mixin create-helper-padding($measure-list: (), $important: false, $prefix: "") {
+
+  @each $name, $val in $measure-list {
+    .#{$prefix}pt-#{$name} {
+      padding-top: #{$val} #{if($important == true, "!important", "")};
+    }
+    .#{$prefix}pb-#{$name} {
+      padding-bottom: #{$val} #{if($important == true, "!important", "")};
+    }
+    .#{$prefix}pl-#{$name} {
+      padding-left: #{$val} #{if($important == true, "!important", "")};
+    }
+    .#{$prefix}pr-#{$name} {
+      padding-right: #{$val} #{if($important == true, "!important", "")};
+    }
+    .#{$prefix}px-#{$name} {
+      padding-right: #{$val} #{if($important == true, "!important", "")};
+      padding-left: #{$val} #{if($important == true, "!important", "")};
+    }
+    .#{$prefix}py-#{$name} {
+      padding-top: #{$val} #{if($important == true, "!important", "")};
+      padding-bottom: #{$val} #{if($important == true, "!important", "")};
+    }
+    .#{$prefix}pa-#{$name} {
+      padding: #{$val} #{if($important == true, "!important", "")};
+    }
+  }
+}

package/src/mixins/_create-instructions.scss

@@ -0,0 +1,11 @@
+/**
+  CSS single instructions generator
+  @param {Array<name,value>[]} measure-list - postfix name and value
+ */
+@mixin create-instructions($instruction, $measure-list: (), $important: false, $prefix: "", $delimiter: "-") {
+  @each $name, $val in $measure-list {
+    .#{$prefix}#{$instruction}#{$delimiter}#{$name} {
+      #{$instruction}: #{$val} #{if($important == true, "!important", "")}
+    }
+  }
+}

package/test/compile.test.js

@@ -0,0 +1,97 @@
+import { describe, it } from "mocha";
+import { expect } from "chai";
+import fs from "fs";
+import util from "util";
+import * as sass from "sass";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+let cssCompiled;
+
+function sassCompiler(){
+    return util.promisify(sass.render)({
+            includePaths: ['./scss'],
+            file: path.join(__dirname, './test.scss'),
+            // outputStyle: 'compressed'
+        })
+        .then(result => result?.css?.toString());
+}
+
+describe("COMPILE", function() {
+    // to remove timeout error
+    this.timeout(10000);
+
+    it('Should compile', async function() {
+        cssCompiled = await sassCompiler();
+        // Not necessary, but let's compile the file
+        fs.writeFile(path.join(__dirname, 'test.css'), cssCompiled, () => {});
+    });
+
+    it('Check some rules', function() {
+        // -- TODO
+        expect(cssCompiled).to.contain('.blue-400-text {');
+        expect(cssCompiled).to.contain('color: rgb(61.4, 139, 253.4) !important');
+        expect(cssCompiled).to.contain('.blue-500-bg {');
+        expect(cssCompiled).to.contain('background: #0d6efd !important');
+        // --
+        expect(cssCompiled).to.contain('--blue-400: 61.4 139 253.4;');
+        expect(cssCompiled).to.contain('--manga-red-500: 212 24 22;');
+        expect(cssCompiled).to.contain('--advanced-brand-instagram: linear-gradient(45deg, #f09433 0%, #e6683c 25%, #dc2743 50%, #cc2366 75%, #bc1888 100%);');
+        expect(cssCompiled).to.contain('.mt-auto {');
+        expect(cssCompiled).to.contain('margin-top: auto;');
+        expect(cssCompiled).to.contain('.my-48 {');
+        expect(cssCompiled).to.contain('margin-top: 48px;');
+        expect(cssCompiled).to.contain('margin-bottom: 48px;');
+        expect(cssCompiled).to.contain('.width-100 {');
+        expect(cssCompiled).to.contain('width: 100% !important;');
+        expect(cssCompiled).to.contain('.flex-gap-24 {');
+        expect(cssCompiled).to.contain('gap: 24px !important;');
+        // -
+        expect(cssCompiled).to.contain('.aspect-ratio-1-1::before {');
+        expect(cssCompiled).to.contain('padding-top: 100%;');
+        expect(cssCompiled).to.contain('.aspect-ratio-16-9::before {');
+        expect(cssCompiled).to.contain('padding-top: 56%;');
+        // -
+        expect(cssCompiled).to.contain('@media all and (-ms-high-contrast: none), (-ms-high-contrast: active) {');
+        expect(cssCompiled).to.contain('@supports (-ms-ime-align: auto) {');
+        expect(cssCompiled).to.contain('@supports (-moz-appearance: none) {');
+        // -- RGB or hex based on color precision. Use sass:color hex or rgb to be sure
+        expect(cssCompiled).to.contain('--color-opaque-1: #111111;');
+        expect(cssCompiled).to.contain('--color-opaque-2: rgb(110.5, 110.5, 110.5);');
+        // --
+        expect(cssCompiled).to.contain('--color-shift-1: rgb(89.25, 89.25, 89.25);');
+        expect(cssCompiled).to.contain('--color-shift-2: rgb(229.5, 229.5, 229.5);');
+        // --
+        expect(cssCompiled).to.contain('--color-contrast-1: #fff;');
+        expect(cssCompiled).to.contain('--color-contrast-2: #000;');
+        // --
+        expect(cssCompiled).to.contain('--color-brightness-1: #fff;');
+        expect(cssCompiled).to.contain('--color-brightness-2: #000;');
+        // --
+        expect(cssCompiled).to.contain('--extract-colors-1: 255 255 255;');
+        expect(cssCompiled).to.contain('--extract-colors-2: 34 34 34;');
+        expect(cssCompiled).to.contain('--extract-colors-3: 221 221 221;');
+        expect(cssCompiled).to.contain('--extract-colors-4: 34, 34, 34;');
+        expect(cssCompiled).to.contain('--extract-colors-5: 221, 221, 221;');
+        expect(cssCompiled).to.contain('--extract-colors-6: 0 255 0;');
+        expect(cssCompiled).to.contain('--extract-colors-7: 0 255 0 / 0.5;');
+        expect(cssCompiled).to.contain('--extract-colors-8: 0, 255, 0;');
+        expect(cssCompiled).to.contain('--extract-colors-9: 0, 255, 0, 0.5;');
+        expect(cssCompiled).to.contain('--extract-colors-10: 0 255 0;');
+        expect(cssCompiled).to.contain('--extract-colors-11: 0 255 0 / 0.5;');
+        expect(cssCompiled).to.contain('--extract-colors-12: 0, 255, 0;');
+        expect(cssCompiled).to.contain('--extract-colors-13: 0, 255, 0, 0.5;');
+        // --
+        expect(cssCompiled).to.contain('--no-null-1: transparent;');
+        expect(cssCompiled).to.contain('--no-null-2: blue;');
+        // --
+        expect(cssCompiled).to.contain('--no-trasparent-1: inherit;');
+        expect(cssCompiled).to.contain('--no-trasparent-2: inherit;');
+        expect(cssCompiled).to.contain('--no-trasparent-3: #123456;');
+        // --
+        expect(cssCompiled).to.contain('--map-deep-get: 10px;');
+    });
+});

package/test/lint.test.js

@@ -0,0 +1,50 @@
+import { describe, it } from 'mocha';
+import { expect } from "chai";
+import stylelint from "stylelint";
+import path from "path";
+import styleLintFormatter from "stylelint-config-standard-scss";
+import { fileURLToPath } from "url";
+
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+
+describe("LINT", function() {
+    // to remove timeout error
+    this.timeout(10000);
+
+    it('Generic linting', async () => {
+        return stylelint.lint({
+            configFile: path.join(__dirname, '../.stylelintrc.json'),
+            ignorePath: path.join(__dirname, '../.stylelintignore'),
+            formatter: styleLintFormatter,
+            files: [
+                path.join(__dirname, './test.scss'),
+            ],
+        })
+            .then(function ({ errored, report }) {
+                if(!errored)
+                    return false;
+                // show me errors
+                const reportsArray = JSON.parse(report);
+                for(let i = reportsArray.length; i--; ){
+                    const reportKeys = Object.keys(reportsArray[i]);
+                    for(let k = reportKeys.length; k--; ){
+                        const reportsValues = reportsArray[i][reportKeys[k]];
+                        if(reportsValues.length <= 0)
+                            continue;
+                        if(Array.isArray(reportsValues)){
+                            console.log("-----------" + reportKeys[k] + "-----------");
+                            for(let x = reportsValues.length; x--; )
+                                console.log(reportsValues[x]);
+                        }else{
+                            console.log(reportKeys[k] + ": " + reportsValues);
+                        }
+                    }
+                }
+                return true;
+            })
+            .then(result => expect(result).to.be.false);
+    });
+});