beathers 5.7.6 → 5.9.1

package/scss/functions/_validations.scss

@@ -1,251 +1,293 @@
-@use 'sass:meta';
-@use 'sass:list';
-@use 'sass:map';
-@use 'sass:string';
-@use '../variables' as vars;
-@use '../settings/defaults' as defs;
-@use '../settings/configs' as configs;
-
-// Definitions
-$opacities: if(vars.$opacities != (), vars.$opacities, defs.$opacities);
-
-// Basics validations functions
-
-// @function number
-// @description Validates if a value is a number.
-// @param {*} $number - The value to validate.
-// @param {String | Null} $in - Optional context for the error message.
-// @return {*} The original value if it's a number.
-// @error If the value is not a number.
-@function number($number, $in: null) {
-  @if $number != null and (meta.type-of($number) != 'number') {
-    $in: if($in != null, ' | in #{$in}', '.');
-    @error '❌ Error at "validate.number()": Please enter a valid number | Expected a number, but got "#{$number}"#{$in}';
-  }
-  @return $number;
-}
-
-// @function string
-// @description Validates if a value is a string.
-// @param {*} $string - The value to validate.
-// @param {String | Null} $in - Optional context for the error message.
-// @return {*} The original value if it's a string.
-// @error If the value is not a string.
-@function string($string, $in: null) {
-  @if $string != null and (meta.type-of($string) != 'string') {
-    $in: if($in != null, ' | in #{$in}', '.');
-    @error '❌ Error at "validate.string()": Please enter a valid string | Expected a string, but got "#{$string}"#{$in}';
-  }
-  @return $string;
-}
-
-// @function boolean
-// @description Validates if a value is a boolean.
-// @param {*} $boolean - The value to validate.
-// @param {String | Null} $in - Optional context for the error message.
-// @return {*} The original value if it's a boolean.
-// @error If the value is not a boolean.
-@function boolean($boolean, $in: null) {
-  @if $boolean != null and (meta.type-of($boolean) != 'bool') {
-    $in: if($in != null, ' | in #{$in}', '.');
-    @error '❌ Error at "validate.boolean()": Please enter a valid boolean | Expected a (true or false), but got "#{$boolean}"#{$in}';
-  }
-  @return $boolean;
-}
-
-// @function notNull
-// @description Validates if a value is not null.
-// @param {*} $value - The value to validate.
-// @param {String | Null} $in - Optional context for the error message.
-// @return {*} The original value if it's not null.
-// @error If the value is null.
-@function notNull($value, $in: null) {
-  @if $value == null {
-    $in: if($in != null, ' | in #{$in}', '.');
-    @error '❌ Error at "validate.notNull()": Please enter a valid value | Value must not be null#{$in}';
-  }
-  @return $value;
-}
-
-// Colors validations functions
-
-// @function opacity
-// @description Validates if a value is a valid opacity (number between 0 and 1).
-// @param {*} $opacity - The value to validate.
-// @param {String | Null} $in - Optional context for the error message.
-// @return {*} The original value if it's a valid opacity.
-// @error If the value is not a number or not between 0 and 1.
-@function opacity($opacity, $in: null) {
-  @if $opacity != null and (meta.type-of($opacity) != 'number' or $opacity < 0 or $opacity > 1) {
-    $in: if($in != null, ' | in #{$in}', '.');
-    @error '❌ Error at "validate.opacity()": Please enter a valid number | Opacity must be a number between 0 and 1. You entered: "#{$opacity}"#{$in}';
-  }
-  @return $opacity;
-}
-
-// @function colorMode
-// @description Validates if a value is a valid color mode ('light' or 'dark').
-// @param {*} $mode - The value to validate.
-// @param {String | Null} $in - Optional context for the error message.
-// @return {*} The original value if it's a valid color mode.
-// @error If the value is not 'light' or 'dark'.
-@function colorMode($mode, $in: null) {
-  @if $mode != null and not($mode == 'light' or $mode == 'dark') {
-    $in: if($in != null, ' | in #{$in}', '.');
-    @error '❌ Error at "validate.colorMode()": Please enter a valid mode | Allowed values are "light" or "dark"#{$in}';
-  }
-  @return $mode;
-}
-
-// @function hexColor
-// @description Validates if a value is a valid hex color.
-// @param {String} $key - The key name of the color (for error messages).
-// @param {*} $value - The value to validate.
-// @param {String | Null} $in - Optional context for the error message.
-// @return {*} The original value if it's a valid hex color.
-// @error If the value is null, not a string/color, or doesn't start with '#'.
-@function hexColor($key, $value, $in: null) {
-  $in: if($in != null, ' | in #{$in}', '.');
-
-  @if $value == null {
-    @error '❌ Error at "validate.hexColor()": Invalid "#{$key}" value | "#{$key}" value is null#{$in}';
-  } @else if meta.type-of($value) != 'string' and meta.type-of($value) != 'color' {
-    @error '❌ Error at "validate.hexColor()": Invalid "#{$key}" value | "#{$key}" value must be a string or color, got type #{meta.type-of($value)}#{$in}';
-  } @else if meta.type-of($value) == 'string' and string.index($value, '#') != 1 {
-    @error '❌ Error at "validate.hexColor()": Invalid "#{$key}" value | "#{$key}" value must start with "#", got "#{$value}"#{$in}';
-  }
-
-  @return $value;
-}
-
-// Map validations functions
-
-// @function map
-// @description Validates if a value is a map.
-// @param {*} $map - The value to validate.
-// @param {String | Null} $in - Optional context for the error message.
-// @return {*} The original value if it's a map.
-// @error If the value is not a map.
-@function map($map, $in: null) {
-  @if meta.type-of($map) != map {
-    $in: if($in != null, ' | in #{$in}', '.');
-    @error '❌ Error at "validate.map()": Invalid type provided | Expected a map, but got "#{$map}" of type "#{meta.type-of($map)}"#{$in}';
-  }
-  @return $map;
-}
-
-// @function mapItem
-// @description Validates if a map contains a specific key.
-// @param {Map} $map - The map to validate.
-// @param {String} $key - The key to check for.
-// @param {List} $expectedKeys - A list of expected keys (for error messages).
-// @param {String | Null} $in - Optional context for the error message.
-// @return {Map} The original map if the key exists.
-// @error If the key is missing from the map.
-@function mapItem($map, $key, $expectedKeys, $in: null) {
-  @if not map.has-key($map, $key) {
-    $in: if($in != null, ' | in #{$in}', '.');
-    @error '❌ Error at "validate.mapItem()": Missing key | Missing key "#{$key}" in the map "#{$map}" | Expected keys: "#{$expectedKeys}"#{$in}';
-  }
-  @return $map;
-}
-
-// List validations functions
-
-// @function list
-// @description Validates if a value is a list. If it's a single string, number, boolean, or color, it's converted to a single-item list.
-// @param {*} $list - The value to validate.
-// @param {String | Null} $in - Optional context for the error message.
-// @return {List} The original value if it's a list, or a new list containing the value.
-// @error If the value is not a list and cannot be converted.
-@function list($list, $in: null) {
-  $list-type: meta.type-of($list);
-
-  @if $list != null and $list-type != 'list' {
-    @if $list-type == 'string' or $list-type == 'number' or $list-type == 'bool' or $list-type == 'color' {
-      @return ($list);
-    } @else {
-      $in: if($in != null, ' | in #{$in}', '.');
-      @error '❌ Error at "validate.list()": Please enter a valid list | Expected a list, but got "#{$list}" of type "#{$list-type}"#{$in}';
-    }
-  }
-
-  @return $list;
-}
-
-// @function listItem
-// @description Validates if an item exists in a list.
-// @param {List} $list - The list to search in.
-// @param {*} $item - The item to search for.
-// @param {String | Null} $in - Optional context for the error message.
-// @return {*} The item if it's found in the list.
-// @error If the item is not found in the list.
-@function listItem($list, $item, $in: null) {
-  @if not list.index($list, $item) {
-    $in: if($in != null, ' | in #{$in}', '.');
-    @error '❌ Error at "validate.listItem()": Invalid item | Missing item "#{$item}" not found in the list "#{$list}"#{$in}';
-  }
-  @return $item;
-}
-
-// Custom colors validations functions
-
-// @function colorMap
-// @description Validates a map of colors, ensuring each color has 'light' and 'dark' variants that are valid hex colors.
-// @param {Map} $map - The color map to validate.
-// @param {String | Null} $in - Optional context for the error message.
-// @return {Map} The original map if all colors and variants are valid.
-// @error If the map structure is incorrect or color values are invalid.
-@function colorMap($map, $in: null) {
-  $mapVal: map($map);
-
-  @each $key, $value in $map {
-    $mapVal: map($value, $in);
-    $lightKey: colorMode($value, $in);
-    $darkKey: colorMode($value, $in);
-    $light: hexColor('#{$key}.light', map.get($value, 'light'), $in);
-    $dark: hexColor('#{$key}.dark', map.get($value, 'dark'), $in);
-  }
-
-  @return $map;
-}
-
-// @function colorOpacity
-// @description Validates if an opacity value is one of the predefined opacities in `$opacities`.
-// @param {*} $opacity - The opacity value to validate.
-// @param {String | Null} $in - Optional context for the error message.
-// @return {*} The original opacity value if it's valid.
-// @error If the opacity value is not in `$opacities`.
-@function colorOpacity($opacity, $in: null) {
-  @if $opacity != null and $opacity != 100 and not(list.index($opacities, $opacity)) {
-    $in: if($in != null, ' | in #{$in}', '.');
-    @error '❌ Error at "validate.colorOpacity()": Invalid color property value | Expected one of (#{$opacities}), but got "#{$opacity}"#{$in}';
-  }
-  @return $opacity;
-}
-
-// @function colorProperty
-// @description Validates if a color property value is one of the allowed values in `configs.$colorsPropertiesMap`.
-// @param {*} $value - The color property value to validate.
-// @param {String | Null} $in - Optional context for the error message.
-// @return {*} The original value if it's a valid color property.
-// @error If the value is not an allowed color property.
-@function colorProperty($value, $in: null) {
-  @if $value != null and not(list.index(map.values(configs.$colorsPropertiesMap), $value)) {
-    @error '❌ Error at "validate.colorProperty()": Invalid color property value | Expected one of #{map.values(configs.$colorsPropertiesMap)}, but got "#{$value}"#{$in}';
-  }
-  @return $value;
-}
-
-// @function colorClass
-// @description Validates if a color class value is one of the allowed keys in `configs.$colorsPropertiesMap`.
-// @param {*} $value - The color class value to validate.
-// @param {String | Null} $in - Optional context for the error message.
-// @return {*} The original value if it's a valid color class.
-// @error If the value is not an allowed color class.
-@function colorClass($value, $in: null) {
-  @if $value != null and not($value == null or list.index(map.keys(configs.$colorsPropertiesMap), $value)) {
-    @error '❌ Error at "validate.colorClass()": Invalid color class value | Expected one of #{map.keys(configs.$colorsPropertiesMap)}, but got "#{$value}"#{$in}';
-  }
-  @return $value;
-}
+@use 'sass:meta';
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:string';
+@use '../variables' as vars;
+@use '../settings/defaults' as defs;
+@use '../settings/configs' as configs;
+
+// Definitions
+$opacities: if(
+  sass(vars.$opacities != null): vars.$opacities; else: defs.$opacities
+);
+
+// Basics validations functions
+
+// @function number
+// @description Validates if a value is a number.
+// @param {*} $number - The value to validate.
+// @param {String | Null} $in - Optional context for the error message.
+// @return {*} The original value if it's a number.
+// @error If the value is not a number.
+@function number($number, $in: null) {
+  @if $number != null and (meta.type-of($number) != 'number') {
+    $in: if(
+      sass($in != null): ' | in #{$in}' ; else: '.'
+    );
+    @debug '❌ Error at "validate.number()": Please enter a valid number | Expected a number, but got "#{$number}"#{$in}';
+    @return null;
+  }
+  @return $number;
+}
+
+// @function string
+// @description Validates if a value is a string.
+// @param {*} $string - The value to validate.
+// @param {String | Null} $in - Optional context for the error message.
+// @return {*} The original value if it's a string.
+// @error If the value is not a string.
+@function string($string, $in: null) {
+  @if $string != null and (meta.type-of($string) != 'string') {
+    $in: if(
+      sass($in != null): ' | in #{$in}' ; else: '.'
+    );
+    @debug '❌ Error at "validate.string()": Please enter a valid string | Expected a string, but got "#{$string}"#{$in}';
+    @return null;
+  }
+  @return $string;
+}
+
+// @function boolean
+// @description Validates if a value is a boolean.
+// @param {*} $boolean - The value to validate.
+// @param {String | Null} $in - Optional context for the error message.
+// @return {*} The original value if it's a boolean.
+// @error If the value is not a boolean.
+@function boolean($boolean, $in: null) {
+  @if $boolean != null and (meta.type-of($boolean) != 'bool') {
+    $in: if(
+      sass($in != null): ' | in #{$in}' ; else: '.'
+    );
+    @debug '❌ Error at "validate.boolean()": Please enter a valid boolean | Expected a (true or false), but got "#{$boolean}"#{$in}';
+    @return null;
+  }
+  @return $boolean;
+}
+
+// @function notNull
+// @description Validates if a value is not null.
+// @param {*} $value - The value to validate.
+// @param {String | Null} $in - Optional context for the error message.
+// @return {*} The original value if it's not null.
+// @error If the value is null.
+@function notNull($value, $in: null) {
+  @if $value == null {
+    $in: if(
+      sass($in != null): ' | in #{$in}' ; else: '.'
+    );
+    @debug '❌ Error at "validate.notNull()": Please enter a valid value | Value must not be null#{$in}';
+    @return null;
+  }
+  @return $value;
+}
+
+// Colors validations functions
+
+// @function opacity
+// @description Validates if a value is a valid opacity (number between 0 and 1).
+// @param {*} $opacity - The value to validate.
+// @param {String | Null} $in - Optional context for the error message.
+// @return {*} The original value if it's a valid opacity.
+// @error If the value is not a number or not between 0 and 1.
+@function opacity($opacity, $in: null) {
+  @if $opacity != null and (meta.type-of($opacity) != 'number' or $opacity < 0 or $opacity > 1) {
+    $in: if(
+      sass($in != null): ' | in #{$in}' ; else: '.'
+    );
+    @debug '❌ Error at "validate.opacity()": Please enter a valid number | Opacity must be a number between 0 and 1. You entered: "#{$opacity}"#{$in}';
+    @return null;
+  }
+  @return $opacity;
+}
+
+// @function colorMode
+// @description Validates if a value is a valid color mode ('light' or 'dark').
+// @param {*} $mode - The value to validate.
+// @param {String | Null} $in - Optional context for the error message.
+// @return {*} The original value if it's a valid color mode.
+// @error If the value is not 'light' or 'dark'.
+@function colorMode($mode, $in: null) {
+  @if $mode != null and not($mode == 'light' or $mode == 'dark') {
+    $in: if(
+      sass($in != null): ' | in #{$in}' ; else: '.'
+    );
+    @debug '❌ Error at "validate.colorMode()": Please enter a valid mode | Allowed values are "light" or "dark"#{$in}';
+    @return null;
+  }
+  @return $mode;
+}
+
+// @function hexColor
+// @description Validates if a value is a valid hex color.
+// @param {String} $key - The key name of the color (for error messages).
+// @param {*} $value - The value to validate.
+// @param {String | Null} $in - Optional context for the error message.
+// @return {*} The original value if it's a valid hex color.
+// @error If the value is null, not a string/color, or doesn't start with '#'.
+@function hexColor($key, $value, $in: null) {
+  $in: if(
+    sass($in != null): ' | in #{$in}' ; else: '.'
+  );
+
+  @if $value == null {
+    @debug '❌ Error at "validate.hexColor()": Invalid "#{$key}" value | "#{$key}" value is null#{$in}';
+    @return null;
+  } @else if meta.type-of($value) != 'string' and meta.type-of($value) != 'color' {
+    @debug '❌ Error at "validate.hexColor()": Invalid "#{$key}" value | "#{$key}" value must be a string or color, got type #{meta.type-of($value)}#{$in}';
+    @return null;
+  } @else if meta.type-of($value) == 'string' and string.index($value, '#') != 1 {
+    @debug '❌ Error at "validate.hexColor()": Invalid "#{$key}" value | "#{$key}" value must start with "#", got "#{$value}"#{$in}';
+    @return null;
+  }
+
+  @return $value;
+}
+
+// Map validations functions
+
+// @function map
+// @description Validates if a value is a map.
+// @param {*} $map - The value to validate.
+// @param {String | Null} $in - Optional context for the error message.
+// @return {*} The original value if it's a map.
+// @error If the value is not a map.
+@function map($map, $in: null) {
+  @if meta.type-of($map) != map {
+    $in: if(
+      sass($in != null): ' | in #{$in}' ; else: '.'
+    );
+    @debug '❌ Error at "validate.map()": Invalid type provided | Expected a map, but got "#{$map}" of type "#{meta.type-of($map)}"#{$in}';
+    @return null;
+  }
+  @return $map;
+}
+
+// @function mapItem
+// @description Validates if a map contains a specific key.
+// @param {Map} $map - The map to validate.
+// @param {String} $key - The key to check for.
+// @param {List} $expectedKeys - A list of expected keys (for error messages).
+// @param {String | Null} $in - Optional context for the error message.
+// @return {Map} The original map if the key exists.
+// @error If the key is missing from the map.
+@function mapItem($map, $key, $expectedKeys, $in: null) {
+  @if not map.has-key($map, $key) {
+    $in: if(
+      sass($in != null): ' | in #{$in}' ; else: '.'
+    );
+    @debug '❌ Error at "validate.mapItem()": Missing key | Missing key "#{$key}" in the map "#{$map}" | Expected keys: "#{$expectedKeys}"#{$in}';
+    @return null;
+  }
+  @return $map;
+}
+
+// List validations functions
+
+// @function list
+// @description Validates if a value is a list. If it's a single string, number, boolean, or color, it's converted to a single-item list.
+// @param {*} $list - The value to validate.
+// @param {String | Null} $in - Optional context for the error message.
+// @return {List} The original value if it's a list, or a new list containing the value.
+// @error If the value is not a list and cannot be converted.
+@function list($list, $in: null) {
+  $list-type: meta.type-of($list);
+
+  @if $list != null and $list-type != 'list' {
+    @if $list-type == 'string' or $list-type == 'number' or $list-type == 'bool' or $list-type == 'color' {
+      @return ($list);
+    } @else {
+      $in: if(
+        sass($in != null): ' | in #{$in}' ; else: '.'
+      );
+      @debug '❌ Error at "validate.list()": Please enter a valid list | Expected a list, but got "#{$list}" of type "#{$list-type}"#{$in}';
+      @return null;
+    }
+  }
+
+  @return $list;
+}
+
+// @function listItem
+// @description Validates if an item exists in a list.
+// @param {List} $list - The list to search in.
+// @param {*} $item - The item to search for.
+// @param {String | Null} $in - Optional context for the error message.
+// @return {*} The item if it's found in the list.
+// @error If the item is not found in the list.
+@function listItem($list, $item, $in: null) {
+  @if not list.index($list, $item) {
+    $in: if(
+      sass($in != null): ' | in #{$in}' ; else: '.'
+    );
+    @debug '❌ Error at "validate.listItem()": Invalid item | Missing item "#{$item}" not found in the list "#{$list}"#{$in}';
+    @return null;
+  }
+  @return $item;
+}
+
+// Custom colors validations functions
+
+// @function colorMap
+// @description Validates a map of colors, ensuring each color has 'light' and 'dark' variants that are valid hex colors.
+// @param {Map} $map - The color map to validate.
+// @param {String | Null} $in - Optional context for the error message.
+// @return {Map} The original map if all colors and variants are valid.
+// @error If the map structure is incorrect or color values are invalid.
+@function colorMap($map, $in: null) {
+  $mapVal: map($map);
+
+  @each $key, $value in $map {
+    $mapVal: map($value, $in);
+    $lightKey: colorMode($value, $in);
+    $darkKey: colorMode($value, $in);
+    $light: hexColor('#{$key}.light', map.get($value, 'light'), $in);
+    $dark: hexColor('#{$key}.dark', map.get($value, 'dark'), $in);
+  }
+
+  @return $map;
+}
+
+// @function colorOpacity
+// @description Validates if an opacity value is one of the predefined opacities in `$opacities`.
+// @param {*} $opacity - The opacity value to validate.
+// @param {String | Null} $in - Optional context for the error message.
+// @return {*} The original opacity value if it's valid.
+// @error If the opacity value is not in `$opacities`.
+@function colorOpacity($opacity, $in: null) {
+  @if $opacity != null and $opacity != 100 and not(list.index($opacities, $opacity)) {
+    $in: if(
+      sass($in != null): ' | in #{$in}' ; else: '.'
+    );
+    @debug '❌ Error at "validate.colorOpacity()": Invalid color property value | Expected one of (#{$opacities}), but got "#{$opacity}"#{$in}';
+    @return null;
+  }
+  @return $opacity;
+}
+
+// @function colorProperty
+// @description Validates if a color property value is one of the allowed values in `configs.$colorsPropertiesMap`.
+// @param {*} $value - The color property value to validate.
+// @param {String | Null} $in - Optional context for the error message.
+// @return {*} The original value if it's a valid color property.
+// @error If the value is not an allowed color property.
+@function colorProperty($value, $in: null) {
+  @if $value != null and not(list.index(map.values(configs.$colorsPropertiesMap), $value)) {
+    @debug '❌ Error at "validate.colorProperty()": Invalid color property value | Expected one of #{map.values(configs.$colorsPropertiesMap)}, but got "#{$value}"#{$in}';
+    @return null;
+  }
+  @return $value;
+}
+
+// @function colorClass
+// @description Validates if a color class value is one of the allowed keys in `configs.$colorsPropertiesMap`.
+// @param {*} $value - The color class value to validate.
+// @param {String | Null} $in - Optional context for the error message.
+// @return {*} The original value if it's a valid color class.
+// @error If the value is not an allowed color class.
+@function colorClass($value, $in: null) {
+  @if $value != null and not($value == null or list.index(map.keys(configs.$colorsPropertiesMap), $value)) {
+    @debug '❌ Error at "validate.colorClass()": Invalid color class value | Expected one of #{map.keys(configs.$colorsPropertiesMap)}, but got "#{$value}"#{$in}';
+    @return null;
+  }
+  @return $value;
+}