beathers 5.0.0

package/src/scss/functions/_others.scss

@@ -0,0 +1,83 @@
+@use "sass:map";
+@use "../settings/configs" as configs;
+@use "../functions/validations" as val;
+
+// @function shadowValue
+// @description Converts a unitless number to a pixel value for shadows, unless the value is 0.
+// @param {Number} $value - The shadow value.
+// @return {String} The shadow value with "px" appended, or 0.
+@function shadowValue($value) {
+  @return if($value != 0, #{$value}#{"px"}, $value);
+}
+
+// @mixin gridDivision
+// @description Generates CSS grid classes for creating grid layouts.
+// @param {String} $axis - The grid axis ('column' or 'row').
+// @param {String | Null} $size - A size prefix for the generated classes (e.g., 'sm', 'md').
+// @param {String} $divider - A divider string for the generated classes (e.g., '-').
+@mixin gridDivision($axis, $size, $divider) {
+  // Validate parameters
+  $checkedAxis: val.listItem((column, row), $axis, "gridDivision.axis");
+  $checkedBase: val.number(configs.$axisDivisions, "gridDivision.axisDivisions");
+
+  $type: if($axis == "column", "col", "row");
+  $mainClass: if($size, "#{$size}#{$divider}#{$type}s", "#{$type}s");
+  $subClass: if($size, "#{$size}#{$divider}#{$type}", $type);
+
+  @for $i from 0 through configs.$axisDivisions {
+    @if ($i > 0) {
+      &.#{$mainClass}#{\:}#{$i} {
+        grid-template-#{$axis}s: repeat($i, 1fr);
+      }
+    }
+
+    $axisProperty: if($i == 0, "grid-#{$axis}-end", "grid-#{$axis}");
+    $class: if($i == 0, auto, $i);
+    $value: if($i == 0, -1, "span #{$i}");
+
+    > .#{$subClass}#{\:}#{$class} {
+      #{$axisProperty}: #{$value};
+    }
+  }
+}
+
+// @mixin flexDivision
+// @description Generates CSS flexbox classes for creating flexible layouts.
+// @param {String} $axis - The flex axis ('width' or 'height').
+// @param {String} $type - The type of flex items ('col', 'cols', 'row', 'rows').
+// @param {String | Null} $size - A size prefix for the generated classes (e.g., 'sm', 'md').
+// @param {String} $divider - A divider string for the generated classes (e.g., '-').
+@mixin flexDivision($axis, $type, $size, $divider) {
+  // Validate parameters
+  $checkedAxis: val.listItem((width, height), $axis, "flexDivision.axis");
+  $checkedType: val.listItem(("col", "cols", "rows", "row"), $type, "flexDivision.type");
+  $checkedBase: val.number(configs.$axisDivisions, "flexDivision.axisDivisions");
+
+  $mainClass: if($size, "#{$size}#{$divider}#{$type}", $type);
+
+  @if (not $size) and $type == "cols" or $type == "rows" {
+    > * {
+      flex: 0 0 auto;
+      max-#{$axis}: 100%;
+    }
+  }
+
+  @for $i from 0 through configs.$axisDivisions {
+    @if $type == "cols" or $type == "rows" {
+      $class: if($i == 0, auto, $i);
+      $axisSize: if($i == 0, auto, calc(100% / $i));
+
+      &.#{$mainClass}#{\:}#{$class} > * {
+        #{$axis}: if($size, $axisSize !important, $axisSize);
+      }
+    } @else if $type == "col" or $type == "row" {
+      $axisSize: if($i == 0, 100%, calc(($i / configs.$axisDivisions) * 100%));
+      $class: if($i == 0, "", $i);
+      $classSize: if($i == 0, #{$class}, #{\:}#{$class});
+
+      > .#{$mainClass}#{$classSize} {
+        #{$axis}: if($size, $axisSize !important, $axisSize);
+      }
+    }
+  }
+}

package/src/scss/functions/_typographic.scss

@@ -0,0 +1,125 @@
+@use 'sass:string';
+@use 'sass:map';
+@use '../settings/defaults' as vars;
+@use '../functions/validations' as val;
+@use '../settings/configs' as configs;
+
+// Font Face Mixin
+// --------------------------------------
+// Generates an @font-face rule.
+//
+// @param {String} $title - The base name of the font (e.g., "OpenSans").
+// @param {String} $weight - The font weight key (e.g., "regular", "bold").
+// @param {String} $format - The font file format (e.g., "woff2").
+// @param {String} $style - The font style (e.g., "normal", "italic").
+// @param {Number} $index [0] - An index appended to the font-family name if multiple fonts share the same weight name.
+// @param {String | Null} $unicode [null] - Optional unicode range for the font.
+// @param {Boolean} $isLocal [true] - Whether the font is hosted locally or externally.
+// @param {String} $externalUrl [""] - The URL for externally hosted fonts (if $isLocal is false).
+//
+// @example scss
+//   @include font("OpenSans", "regular", "woff2", "normal", 0, null, true);
+//   // Generates:
+//   // @font-face {
+//   //   font-family: "regular"; // Or "regular-0" if $index is 0 but other fonts exist with same weight
+//   //   font-weight: 400;
+//   //   font-style: normal;
+//   //   font-display: swap;
+//   //   src: local("OpenSans-regular"),
+//   //        url("../fonts/OpenSans-regular.woff2") format("woff2");
+//   // }
+//
+//   @include font("Roboto", "bold", "ttf", "normal", 1, "U+000-5FF", false, "https://fonts.gstatic.com/s/roboto/v20/KFOlCnqEu92Fr1MmWUlfBBc4.ttf");
+//   // Generates:
+//   // @font-face {
+//   //   font-family: "bold-1";
+//   //   font-weight: 700;
+//   //   font-style: normal;
+//   //   font-display: swap;
+//   //   src: url("https://fonts.gstatic.com/s/roboto/v20/KFOlCnqEu92Fr1MmWUlfBBc4.ttf");
+//   //   unicode-range: U+000-5FF;
+//   // }
+//
+@mixin font($title, $weight, $format, $style, $index: 0, $unicode: null, $isLocal: true, $externalUrl: '') {
+  // Validate parameters
+  $checkedIsLocal: val.boolean($isLocal, '#{$title}.font().local');
+  $checkedTitle: val.string($title, '#{$title}.font().title');
+  $checkedWeight: val.mapItem(
+    configs.$fontWeightsValues,
+    $weight,
+    configs.$fontWeightsValues,
+    'Typographic.fontFace.weights.#{$weight}'
+  );
+  $checkedStyle: val.listItem(('normal', 'italic', 'oblique'), $style, '#{$title}.font().weights.#{$style}');
+  $checkIndex: val.number($index, '#{$title}.font().index');
+  $checkedFormat: val.string($format, '#{$title}.font().format');
+
+  @if (not($isLocal)) {
+    $checkedExternalUrl: val.string($externalUrl, 'Typographic.fontFace.externalUrl');
+  }
+
+  $name: if($index == 0, $title, '#{$title}-#{$index}');
+  $weightValue: map.get(configs.$fontWeightsValues, $weight);
+
+  @font-face {
+    font-family: $name;
+    font-weight: $weightValue;
+    font-style: $style;
+    font-display: swap;
+
+    @if ($isLocal) {
+      src:
+        local('#{$title}-#{$weight}'),
+        url(string.unquote('#{vars.$fontMainPath}#{$title}-#{$weight}.#{$format}')) format('#{$format}');
+    } @else {
+      src: url(string.unquote('#{$externalUrl}'));
+    }
+
+    @if $unicode {
+      // Validate parameters
+      $checkedUnicode: val.string($unicode, '#{$title}.font().unicode');
+
+      unicode-range: string.unquote($unicode);
+    }
+  }
+}
+
+// Font Shapes Mixin
+// --------------------------------------
+// Applies text transformation, decoration, or style properties to a class.
+//
+// @param {String} $class - The CSS class name to apply the style to.
+// @param {String} $type - The type of shape property ("transform", "decoration", "styles").
+// @param {String} $value - The value for the shape property (e.g., "uppercase", "underline", "italic").
+// @param {String | Null} $size [null] - Optional size prefix for responsive classes, determines if `!important` is added.
+//
+// @example scss
+//   @include fontShapes("uppercase", "transform", "uppercase");
+//   // Generates:
+//   // .uppercase {
+//   //   text-transform: uppercase;
+//   // }
+//
+//   @include fontShapes("md:underline", "decoration", "underline", "md");
+//   // Generates:
+//   // .md\\:underline {
+//   //   text-decoration: underline !important;
+//   // }
+//
+@mixin fontShapes($class, $type, $value) {
+  $shapeList: map.get(configs.$fontShapes, $type);
+
+  // Validate parameters
+  $checkedType: val.mapItem(configs.$fontShapes, $type, configs.$fontShapes, 'fontShapes().#{$type}');
+  $checkedValue: val.listItem($shapeList, $value, 'fontShapes().#{$value}');
+
+  .#{$class} {
+    @if $type == 'transform' {
+      text-transform: $value;
+    } @else if $type == 'decoration' {
+      text-decoration: $value;
+    } @else if $type == 'styles' {
+      font-style: $value;
+    }
+  }
+}

package/src/scss/functions/_validations.scss

@@ -0,0 +1,256 @@
+@use "sass:meta";
+@use "sass:list";
+@use "sass:map";
+@use "../settings/configs" as configs;
+
+// 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 str-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 `configs.$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 `configs.$opacities`.
+@function colorOpacity($opacity, $in: null) {
+  @if $opacity != null and not(list.index(configs.$opacities, $opacity)) {
+    $in: if($in != null, " | in #{$in}", ".");
+    @error '❌ Error at "validate.colorOpacity()": Invalid color property value | Expected one of (#{configs.$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;
+}