beathers 5.7.6 → 5.9.1

package/scss/functions/_colors.scss

@@ -1,230 +1,242 @@
-@use 'sass:color';
-@use 'sass:math';
-@use 'sass:list';
-@use 'sass:map';
-@use '../settings/configs' as configs;
-@use '../settings/index' as settings;
-@use '../variables' as vars;
-@use '../settings/defaults' as defs;
-@use '../functions/validations' as val;
-
-// Definitions
-$colors: if(vars.$colors != (), vars.$colors, defs.$colors);
-$opacities: if(vars.$opacities != (), vars.$opacities, defs.$opacities);
-$useColorsLightMode: if(vars.$useColorsLightMode != null, vars.$useColorsLightMode, settings.$useColorsLightMode);
-$useColorsDarkMode: if(vars.$useColorsDarkMode != null, vars.$useColorsDarkMode, settings.$useColorsDarkMode);
-$useColorsOpacities: if(vars.$useColorsOpacities != null, vars.$useColorsOpacities, settings.$useColorsOpacities);
-
-// Color Convertors ----- ----- ----- -----
-//
-// @function hexToRgba
-// --------------------------------------
-// Converts a hex color value to RGBA format
-//
-// @param {Color} $color - The hex color to convert (e.g. '#ffffff' or '#fff')
-// @param {Number} $opacity - Optional opacity value between 0 and 1 (default: 1)
-// @return {Color} - The color in rgba() format
-//
-// @example scss
-//   color: hexToRgba('#ffffff');
-//   // Returns rgba(255, 255, 255, 1)
-//   color: hexToRgba('#ffffff', 0.5);
-//   // Returns rgba(255, 255, 255, 0.5)
-//   color: hexToRgba('#ffffff80');
-//   // Returns rgba(255, 255, 255, 0.5)
-//
-@function hexToRgba($color, $opacity: 1, $debugIn: null) {
-  // Validate parameters
-  $checkedColor: val.hexColor('color', $color, 'hexToRgba().#{$debugIn}');
-  $checkedOpacity: val.opacity($opacity, 'hexToRgba().#{$debugIn}');
-
-  @return rgba(
-    color.channel($checkedColor, 'red', $space: rgb),
-    color.channel($checkedColor, 'green', $space: rgb),
-    color.channel($checkedColor, 'blue', $space: rgb),
-    $checkedOpacity
-  );
-}
-
-// Use Color ----- ----- ----- -----
-//
-// @function useColor
-// --------------------------------------
-// Retrieves a color from any color map with optional variant and opacity
-//
-// @param {String} $color - The color key to retrieve from the map
-// @param {String} $mode - Optional mode, must be 'light' or 'dark' (default: 'light')
-// @param {Number} $opacity - Optional opacity value between 0 and 100 (default: 100)
-// @param {Map} $map - Optional color map to use (defaults to $colors)
-// @return {Color} - The color value, possibly with applied opacity
-// @throws {Error} - If mode is provided but isn't 'light' or 'dark'
-// @throws {Error} - If opacity is provided but isn't a number between 0 and 100
-//
-// @example scss
-//   // Using default color map ($colors)
-//   color: useColor('primary', 'light', 0.5);
-//   // Returns the light variant of primary color with 50% opacity
-//
-//   // Using a custom color map
-//   color: useColor('secondary', 'dark', null, $customMap);
-//   // Returns the dark variant of secondary color from custom map
-//
-@function useColor($color, $mode: 'light', $opacity: 100) {
-  // Validate parameters
-  $checkedMode: val.colorMode($mode, 'useColor()');
-  $checkedOpacity: val.colorOpacity($opacity, 'useColor()');
-
-  @if $color {
-    $value: map.get($color, $mode);
-
-    @if $checkedOpacity {
-      @return hexToRgba($value, math.div($opacity, 100), 'useColor().#{$value}');
-    } @else {
-      @return $value;
-    }
-  } @else {
-    @return null;
-  }
-}
-
-@function useColorWithMap($color, $mode: 'light', $opacity: 100, $map: $colors) {
-  // Validate parameters
-  $checkedMap: val.map($map, 'useColorWithMap().map');
-
-  $colorValue: map.get($checkedMap, $color);
-  @return useColor($colorValue, $mode, $opacity);
-}
-
-// @mixin useColorProperty
-// --------------------------------------
-// Applies color properties with theme variant support while handling light/dark themes
-// and creating appropriate CSS selectors for different use cases.
-//
-// @param {String} $colorClass - The CSS class name to apply the color to (e.g., 'color-1', 'bg\:color-1')
-// @param {String|Null} $class - The CSS class prefix (e.g., 'bg', 'border', null for 'color')
-// @param {String} $property - The CSS property to set (e.g., 'color', 'background-color')
-// @param {Map} $color - The color map with light/dark variants
-// @param {Map} $map - The parent color map containing all colors
-// @param {Number} $opacity - Optional opacity value between 0-100 (default: 100)
-// @throws {Error} - If provided parameters fail validation through val.* functions
-//
-// @example scss
-//   // Apply primary color as text color with 50% opacity
-//   @include useColorProperty("color-1", null, "color", $primaryColor, $colorsMap, 50);
-//
-//   // Apply primary color as background with full opacity
-//   @include useColorProperty("bg\:color-1", "bg", "background-color", $primaryColor, $colorsMap);
-//
-// Generated Selectors:
-// Each call to this mixin generates three CSS selectors to support different theming approaches:
-//
-// 1. Parent/child relationship: `.light .className`, `.dark .className`
-//    For theme inheritance from parent elements
-//    Example: <div class="light"><span class="color-1">Themed text</span></div>
-//
-// 2. Modifier class: `.className.light`, `.className.dark`
-//    For direct theme application to the element itself
-//    Example: <span class="color-1 light">Themed text</span>
-//
-// 3. Prefixed class: `.light\:className`, `.dark\:className`
-//    For utility-first CSS approaches
-//    Example: <span class="light\:color-1">Themed text</span>
-//
-// Note: When light and dark variants are identical, a single class without theme
-// modifiers is generated to reduce CSS output size.
-@mixin useColorProperty($colorClass, $class, $property, $color, $map, $opacity: 100) {
-  // Validate parameters
-  $checkedClass: val.colorClass($class, 'useColorProperty().class');
-  $checkedProperty: val.colorProperty($property, 'useColorProperty().property');
-  $checkedMap: val.map($map, 'useColorProperty().map');
-  $checkedOpacity: val.colorOpacity($opacity, 'useColorProperty().opacity');
-  $checkedLight: val.mapItem($color, 'light', 'light/dark', 'useColorProperty().color');
-  $checkedDark: val.mapItem($color, 'dark', 'light/dark', 'useColorProperty().color');
-
-  $light: map.get($color, 'light');
-  $dark: map.get($color, 'dark');
-
-  $checkedLightValue: val.hexColor('#{$colorClass}.light', $light, 'root-colors()');
-  $checkedDarkValue: val.hexColor('#{$colorClass}.dark', $dark, 'root-colors()');
-
-  @if $light and $dark and $dark != $light {
-    @if ($useColorsLightMode) {
-      .light .#{$colorClass},
-      .#{$colorClass}.light,
-      .light\:#{$colorClass} {
-        #{$property}: useColor($color, 'light', $opacity);
-      }
-    }
-
-    @if ($useColorsDarkMode) {
-      .dark .#{$colorClass},
-      .#{$colorClass}.dark,
-      .dark\:#{$colorClass} {
-        #{$property}: useColor($color, 'dark', $opacity);
-      }
-    }
-  } @else {
-    .#{$colorClass} {
-      #{$property}: useColor($color, if($light, 'light', 'dark'), $opacity);
-    }
-  }
-}
-
-// Use Colors Map ----- ----- ----- -----
-//
-// @mixin useColorsMap
-// --------------------------------------
-// Creates color utility classes using useColor() function for theme variant handling
-// @param {Map} $map - The color map to use (e.g., $colors)
-// @param {Boolean} $withOpacity - Whether to generate opacity variants (default: true)
-// @throws {Error} - If $map is not a valid map
-//
-// @example scss
-//   @include useColorsMap($themeColors);
-//   // Creates all color classes with theme support
-//   // Generated classes include:
-//   // .color-[colorName], .bg-color-[colorName], .border-color-[colorName]
-//   // With theme variants like .light, .dark
-//   // With optional opacity variants like :50, :75
-//   // With pseudo-class variants like :hover, :focus
-//
-@mixin useColorsMap($map: $colors, $withOpacity: true) {
-  // Validate parameters
-  $checkedMap: val.map($map, 'useColorsMap()');
-  $checkedWithOpacity: val.boolean($withOpacity, 'useColorsMap()');
-
-  @each $color, $modes in $checkedMap {
-    @if $color {
-      @each $class, $property in configs.$colorsPropertiesMap {
-        $mainClass: if($class, '#{$class}#{\:}color-#{$color}', 'color-#{$color}');
-
-        @include useColorProperty($mainClass, $class, $property, $modes, $map);
-
-        @if $checkedWithOpacity and $useColorsOpacities {
-          @each $opacity in $opacities {
-            @include useColorProperty('#{$mainClass}#{\:}#{$opacity}', $class, $property, $modes, $map, $opacity);
-          }
-        }
-
-        @each $pseudoClass, $pseudo in configs.$colorsPseudoMap {
-          @if $pseudoClass != 'placeholder' or ($pseudoClass == 'placeholder' and $class == null) {
-            @include useColorProperty('#{$mainClass}#{\:}#{$pseudoClass}#{$pseudo}', $class, $property, $modes, $map);
-
-            @if $checkedWithOpacity and $useColorsOpacities {
-              @each $opacity in $opacities {
-                @include useColorProperty(
-                  '#{$mainClass}#{\:}#{$opacity}#{\:}#{$pseudoClass}#{$pseudo}',
-                  $class,
-                  $property,
-                  $modes,
-                  $map,
-                  $opacity
-                );
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}
+@use 'sass:color';
+@use 'sass:math';
+@use 'sass:list';
+@use 'sass:map';
+@use '../settings/configs' as configs;
+@use '../settings/index' as settings;
+@use '../variables' as vars;
+@use '../settings/defaults' as defs;
+@use '../functions/validations' as val;
+
+// Definitions
+$colors: if(
+  sass(vars.$colors != null): vars.$colors; else: defs.$colors
+);
+$opacities: if(
+  sass(vars.$opacities != null): vars.$opacities; else: defs.$opacities
+);
+$useColorsLightMode: if(
+  sass(vars.$useColorsLightMode != null): vars.$useColorsLightMode; else: settings.$useColorsLightMode
+);
+$useColorsDarkMode: if(
+  sass(vars.$useColorsDarkMode != null): vars.$useColorsDarkMode; else: settings.$useColorsDarkMode
+);
+$useColorsOpacities: if(
+  sass(vars.$useColorsOpacities != null): vars.$useColorsOpacities; else: settings.$useColorsOpacities
+);
+
+// Color Convertors ----- ----- ----- -----
+//
+// @function hexToRgba
+// --------------------------------------
+// Converts a hex color value to RGBA format
+//
+// @param {Color} $color - The hex color to convert (e.g. '#ffffff' or '#fff')
+// @param {Number} $opacity - Optional opacity value between 0 and 1 (default: 1)
+// @return {Color} - The color in rgba() format
+//
+// @example scss
+//   color: hexToRgba('#ffffff');
+//   // Returns rgba(255, 255, 255, 1)
+//   color: hexToRgba('#ffffff', 0.5);
+//   // Returns rgba(255, 255, 255, 0.5)
+//   color: hexToRgba('#ffffff80');
+//   // Returns rgba(255, 255, 255, 0.5)
+//
+@function hexToRgba($color, $opacity: 1, $debugIn: null) {
+  // Validate parameters
+  $checkedColor: val.hexColor('color', $color, 'hexToRgba().#{$debugIn}');
+  $checkedOpacity: val.opacity($opacity, 'hexToRgba().#{$debugIn}');
+
+  @return rgba(
+    color.channel($checkedColor, 'red', $space: rgb),
+    color.channel($checkedColor, 'green', $space: rgb),
+    color.channel($checkedColor, 'blue', $space: rgb),
+    $checkedOpacity
+  );
+}
+
+// Use Color ----- ----- ----- -----
+//
+// @function useColor
+// --------------------------------------
+// Retrieves a color from any color map with optional variant and opacity
+//
+// @param {String} $color - The color key to retrieve from the map
+// @param {String} $mode - Optional mode, must be 'light' or 'dark' (default: 'light')
+// @param {Number} $opacity - Optional opacity value between 0 and 100 (default: 100)
+// @param {Map} $map - Optional color map to use (defaults to $colors)
+// @return {Color} - The color value, possibly with applied opacity
+// @throws {Error} - If mode is provided but isn't 'light' or 'dark'
+// @throws {Error} - If opacity is provided but isn't a number between 0 and 100
+//
+// @example scss
+//   // Using default color map ($colors)
+//   color: useColor('primary', 'light', 0.5);
+//   // Returns the light variant of primary color with 50% opacity
+//
+//   // Using a custom color map
+//   color: useColor('secondary', 'dark', null, $customMap);
+//   // Returns the dark variant of secondary color from custom map
+//
+@function useColor($color, $mode: 'light', $opacity: 100) {
+  // Validate parameters
+  $checkedMode: val.colorMode($mode, 'useColor()');
+  $checkedOpacity: val.colorOpacity($opacity, 'useColor()');
+
+  @if $color {
+    $value: map.get($color, $mode);
+
+    @if $checkedOpacity {
+      @return hexToRgba($value, math.div($opacity, 100), 'useColor().#{$value}');
+    } @else {
+      @return $value;
+    }
+  } @else {
+    @return null;
+  }
+}
+
+@function useColorWithMap($color, $mode: 'light', $opacity: 100, $map: $colors) {
+  // Validate parameters
+  $checkedMap: val.map($map, 'useColorWithMap().map');
+
+  $colorValue: map.get($checkedMap, $color);
+  @return useColor($colorValue, $mode, $opacity);
+}
+
+// @mixin useColorProperty
+// --------------------------------------
+// Applies color properties with theme variant support while handling light/dark themes
+// and creating appropriate CSS selectors for different use cases.
+//
+// @param {String} $colorClass - The CSS class name to apply the color to (e.g., 'color-1', 'bg\:color-1')
+// @param {String|Null} $class - The CSS class prefix (e.g., 'bg', 'border', null for 'color')
+// @param {String} $property - The CSS property to set (e.g., 'color', 'background-color')
+// @param {Map} $color - The color map with light/dark variants
+// @param {Map} $map - The parent color map containing all colors
+// @param {Number} $opacity - Optional opacity value between 0-100 (default: 100)
+// @throws {Error} - If provided parameters fail validation through val.* functions
+//
+// @example scss
+//   // Apply primary color as text color with 50% opacity
+//   @include useColorProperty("color-1", null, "color", $primaryColor, $colorsMap, 50);
+//
+//   // Apply primary color as background with full opacity
+//   @include useColorProperty("bg\:color-1", "bg", "background-color", $primaryColor, $colorsMap);
+//
+// Generated Selectors:
+// Each call to this mixin generates three CSS selectors to support different theming approaches:
+//
+// 1. Parent/child relationship: `.light .className`, `.dark .className`
+//    For theme inheritance from parent elements
+//    Example: <div class="light"><span class="color-1">Themed text</span></div>
+//
+// 2. Modifier class: `.className.light`, `.className.dark`
+//    For direct theme application to the element itself
+//    Example: <span class="color-1 light">Themed text</span>
+//
+// 3. Prefixed class: `.light\:className`, `.dark\:className`
+//    For utility-first CSS approaches
+//    Example: <span class="light\:color-1">Themed text</span>
+//
+// Note: When light and dark variants are identical, a single class without theme
+// modifiers is generated to reduce CSS output size.
+@mixin useColorProperty($colorClass, $class, $property, $color, $map, $opacity: 100) {
+  // Validate parameters
+  $checkedClass: val.colorClass($class, 'useColorProperty().class');
+  $checkedProperty: val.colorProperty($property, 'useColorProperty().property');
+  $checkedMap: val.map($map, 'useColorProperty().map');
+  $checkedOpacity: val.colorOpacity($opacity, 'useColorProperty().opacity');
+  $checkedLight: val.mapItem($color, 'light', 'light/dark', 'useColorProperty().color');
+  $checkedDark: val.mapItem($color, 'dark', 'light/dark', 'useColorProperty().color');
+
+  $light: map.get($color, 'light');
+  $dark: map.get($color, 'dark');
+
+  $checkedLightValue: val.hexColor('#{$colorClass}.light', $light, 'root-colors()');
+  $checkedDarkValue: val.hexColor('#{$colorClass}.dark', $dark, 'root-colors()');
+
+  @if $light and $dark and $dark != $light {
+    @if ($useColorsLightMode) {
+      .light .#{$colorClass},
+      .#{$colorClass}.light,
+      .light\:#{$colorClass} {
+        #{$property}: useColor($color, 'light', $opacity);
+      }
+    }
+
+    @if ($useColorsDarkMode) {
+      .dark .#{$colorClass},
+      .#{$colorClass}.dark,
+      .dark\:#{$colorClass} {
+        #{$property}: useColor($color, 'dark', $opacity);
+      }
+    }
+  } @else {
+    .#{$colorClass} {
+      #{$property}: useColor($color, if(sass($light): 'light' ; else: 'dark'), $opacity);
+    }
+  }
+}
+
+// Use Colors Map ----- ----- ----- -----
+//
+// @mixin useColorsMap
+// --------------------------------------
+// Creates color utility classes using useColor() function for theme variant handling
+// @param {Map} $map - The color map to use (e.g., $colors)
+// @param {Boolean} $withOpacity - Whether to generate opacity variants (default: true)
+// @throws {Error} - If $map is not a valid map
+//
+// @example scss
+//   @include useColorsMap($themeColors);
+//   // Creates all color classes with theme support
+//   // Generated classes include:
+//   // .color-[colorName], .bg-color-[colorName], .border-color-[colorName]
+//   // With theme variants like .light, .dark
+//   // With optional opacity variants like :50, :75
+//   // With pseudo-class variants like :hover, :focus
+//
+@mixin useColorsMap($map: $colors, $withOpacity: true) {
+  // Validate parameters
+  $checkedMap: val.map($map, 'useColorsMap()');
+  $checkedWithOpacity: val.boolean($withOpacity, 'useColorsMap()');
+
+  @each $color, $modes in $checkedMap {
+    @if $color {
+      @each $class, $property in configs.$colorsPropertiesMap {
+        $mainClass: if(
+          sass($class): '#{$class}#{\:}color-#{$color}' ; else: 'color-#{$color}'
+        );
+
+        @include useColorProperty($mainClass, $class, $property, $modes, $map);
+
+        @if $checkedWithOpacity and $useColorsOpacities {
+          @each $opacity in $opacities {
+            @include useColorProperty('#{$mainClass}#{\:}#{$opacity}', $class, $property, $modes, $map, $opacity);
+          }
+        }
+
+        @each $pseudoClass, $pseudo in configs.$colorsPseudoMap {
+          @if $pseudoClass != 'placeholder' or ($pseudoClass == 'placeholder' and $class == null) {
+            @include useColorProperty('#{$mainClass}#{\:}#{$pseudoClass}#{$pseudo}', $class, $property, $modes, $map);
+
+            @if $checkedWithOpacity and $useColorsOpacities {
+              @each $opacity in $opacities {
+                @include useColorProperty(
+                  '#{$mainClass}#{\:}#{$opacity}#{\:}#{$pseudoClass}#{$pseudo}',
+                  $class,
+                  $property,
+                  $modes,
+                  $map,
+                  $opacity
+                );
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}