unit.gl 0.0.35 → 0.0.39

package/scss/functions/unit/_unit_conversion.scss

@@ -0,0 +1,94 @@
+// ============================================================================
+// Poster
+// ============================================================================
+
+////
+/// 
+/// Unit Functions Module
+/// ===========================================================================
+/// 
+/// @group Unit
+/// @author Scape Agency
+/// @link https://unit.gl
+/// @since 0.1.0 initial release
+/// @todo None
+/// @access public
+/// 
+////
+
+
+// ============================================================================
+// Use
+// ============================================================================
+
+
+// ============================================================================
+// Functions
+// ============================================================================
+
+
+
+
+
+/// Unit Conversion Functions
+/// ---------------------------------------------------------------------------
+/// Create functions to convert between different measurement units, such as
+/// pixels to rem, em to pixels, etc.
+
+@function px_to_rem($size, $base: 16px) {
+    @return $size / $base * 1rem;
+}
+
+@function rem_to_px($size, $base: 16px) {
+    @return $size * $base;
+}
+
+@function em_to_px($size, $context: 16px) {
+    @return $size * $context;
+}
+
+@function px_to_em($size, $context: 16px) {
+    @return $size / $context * 1em;
+}
+
+
+/// Base font-size for the document
+$base-font-size: 16px !default;
+
+/// Validate that the input is a pixel value
+@function validate-px($value) {
+    @if unit($value) != 'px' {
+        @error "Expected a pixel value, but got `#{$value}`.";
+    }
+    @return $value;
+}
+
+/// Convert pixels to rem
+@function px_to_rem($size) {
+    $validated-size: validate-px($size);
+    @return $validated-size / $base-font-size * 1rem;
+}
+
+/// Convert rem to pixels
+@function rem_to_px($size) {
+    @if unit($size) != 'rem' {
+        @error "Expected a rem value, but got `#{$size}`.";
+    }
+    @return $size * $base-font-size;
+}
+
+/// Convert em to pixels
+@function em_to_px($size, $context: $base-font-size) {
+    $validated-context: validate-px($context);
+    @if unit($size) != 'em' {
+        @error "Expected an em value, but got `#{$size}`.";
+    }
+    @return $size * $validated-context;
+}
+
+/// Convert pixels to em
+@function px_to_em($size, $context: $base-font-size) {
+    $validated-size: validate-px($size);
+    $validated-context: validate-px($context);
+    @return $validated-size / $validated-context * 1em;
+}

package/scss/functions/{_unit_functions.scss → unit/_unit_functions.scss}

@@ -1,28 +1,41 @@
-// Copyright 2024 Scape Agency BV
+// ============================================================================
+// Poster
+// ============================================================================
 
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
+////
+/// 
+/// Unit Functions Module
+/// ===========================================================================
+/// 
+/// @group Unit
+/// @author Scape Agency
+/// @link https://unit.gl
+/// @since 0.1.0 initial release
+/// @todo None
+/// @access public
+/// 
+////
 
-// http://www.apache.org/licenses/LICENSE-2.0
 
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
+// ============================================================================
+// Use
+// ============================================================================
 
 
 // ============================================================================
-// Unit | Functions
+// Functions
 // ============================================================================
 
 
+/// 
 /// Strip Unit Function
-/// Function to remove the unit from a numerical value
-/// Ensures compatibility with various SCSS versions
-/// @param $value - The numerical value with or without a unit
-/// @return - The raw numerical value without its unit
+/// ---------------------------------------------------------------------------
+/// 
+/// Removes the unit from a numerical value, ensuring compatibility with various SCSS versions.
+/// 
+/// @param {Number} $value - The numerical value with or without a unit.
+/// @return {Number} - The raw numerical value without its unit, or the original value if unitless or non-numerical.
+/// 
 @function unit_strip($value) {
     // Check if the input is a number with a unit
     @if type-of($value) == "number" and not unitless($value) {
@@ -46,15 +59,20 @@
 }
 
 
+///
 /// Linear Interpolation Function
+/// ---------------------------------------------------------------------------
+/// 
 /// Interpolates linearly between two values across a range, useful for
 /// fluid scaling.
-/// @param $start - Starting value at the lower bound (can include units)
-/// @param $end - Ending value at the upper bound (can include units)
-/// @param $min - Lower bound for interpolation (must be unitless or in 'px')
-/// @param $max - Upper bound for interpolation (must be unitless or in 'px')
-/// @param $actual - Current value to interpolate (default is 100vw)
-/// @return - Interpolated value (in the same units as $start and $end)
+/// 
+/// @param {Number} $start - Starting value at the lower bound (can include units).
+/// @param {Number} $end - Ending value at the upper bound (can include units).
+/// @param {Number} $min - Lower bound for interpolation (must be unitless or in 'px').
+/// @param {Number} $max - Upper bound for interpolation (must be unitless or in 'px').
+/// @param {Number} $actual - Current value to interpolate (default is 100vw).
+/// @return {Number} - Interpolated value (in the same units as $start and $end).
+/// 
 @function linear_interpolation($start, $end, $min, $max, $actual: 100vw) {
 
     // Validate parameters
@@ -92,13 +110,18 @@
 }
 
 
-/// Function: scale_dynamic_clamp
-/// Calculates font size using clamp-based responsive typography
-/// @param $_font_size_min - Minimum font size
-/// @param $_font_size_max - Maximum font size
-/// @param $_viewport_width_min - Minimum viewport width where scaling starts
-/// @param $_viewport_width_max - Maximum viewport width where scaling stops
-/// @return - Calculated size using clamp
+///
+///  Clamp-based Responsive Typography Function
+/// ---------------------------------------------------------------------------
+/// 
+/// Calculates font size using clamp-based responsive typography.
+/// 
+/// @param {Number} $_font_size_min - Minimum font size.
+/// @param {Number} $_font_size_max - Maximum font size.
+/// @param {Number} $_viewport_width_min - Minimum viewport width where scaling starts.
+/// @param {Number} $_viewport_width_max - Maximum viewport width where scaling stops.
+/// @return {Number} - Calculated size using clamp.
+/// 
 @function scale_dynamic_clamp(
     $_viewport_width_min,
     $_viewport_width_max,
@@ -119,10 +142,8 @@
 
 
 
-
-
-// Fluid Typography Mixin
-// ============================================================================
+/// Fluid Typography Mixin
+/// ---------------------------------------------------------------------------
 /// Mixin: fluid_type
 /// Creates fluid typography rules to scale font sizes responsively between a
 /// minimum and maximum viewport width.
@@ -149,7 +170,7 @@
 //     // $u4: $_font_size_max;
 
 //     @if $u1 == $u2 and $u1 == $u3 and $u1 == $u4 {
-//         font-size: $_font_size_min * 16;
+//         font-size: $_font_size_min/// 16;
 //         // Apply fluid font-size between the min and max viewport widths
 //         @media screen and (min-width: $_viewport_width_min) {
 //             font-size: linear_interpolation(
@@ -157,11 +178,11 @@
 //                 $_font_size_max,
 //                 $_viewport_width_min,
 //                 $_viewport_width_max
-//             ) * 16;
+//             )/// 16;
 //         }
 //         // Set to max font-size for viewports wider than the max viewport width
 //         @media screen and (min-width: $_viewport_width_max) {
-//             font-size: $_font_size_max * 16;
+//             font-size: $_font_size_max/// 16;
 //         }
 //     } @else {
 //         @warn "Inconsistent units provided for fluid typography.";
@@ -169,7 +190,20 @@
 // }
 
 
-
+///
+/// Dynamic Scaling Function
+/// ---------------------------------------------------------------------------
+/// 
+/// Calculates font size dynamically based on viewport width, allowing for
+/// fluid scaling.
+/// 
+/// @param {Number} $_viewport_width_min - Minimum viewport width where scaling starts.
+/// @param {Number} $_viewport_width_max - Maximum viewport width where scaling stops.
+/// @param {Number} $_font_size_min - Minimum font size.
+/// @param {Number} $_font_size_max - Maximum font size.
+/// @param {Number} $_current_width - Current viewport width.
+/// @return {Number} - The calculated font size based on the current width, or null if units are inconsistent.
+/// 
 @function scale_dynamic(
     $_viewport_width_min,
     $_viewport_width_max,

package/scss/index.scss

@@ -1,18 +1,3 @@
-// Copyright 2024 Scape Agency BV
-
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-
-// http://www.apache.org/licenses/LICENSE-2.0
-
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-
 @charset "utf-8";
 
 @use "sass:math";
@@ -20,8 +5,9 @@
 @forward "reset";
 @forward "global";
 
-@forward "variables";
 @forward "functions";
+@forward "variables";
 @forward "mixins";
 
 @forward "classes";
+@forward "tags";

package/scss/maps/_color.scss

@@ -0,0 +1,43 @@
+// ============================================================================
+// Poster
+// ============================================================================
+
+////
+/// 
+/// Color Variables Module
+/// ===========================================================================
+/// 
+/// These colors are used for visual guides such as grid overlays, baselines, 
+/// and alignment guides. The colors are defined with varying levels of opacity 
+/// to ensure they are visible yet non-intrusive on the design.
+/// 
+/// @group Color
+/// @author Scape Agency
+/// @link https://unit.gl
+/// @since 0.1.0 initial release
+/// @todo None
+/// @access public
+/// 
+////
+
+
+// ============================================================================
+// Use
+// ============================================================================
+
+
+// ============================================================================
+// Maps
+// ============================================================================
+
+/// Color Set for Easy Adjustments
+/// ---------------------------------------------------------------------------
+/// 
+$guide_colors: (
+    "primary":    $guide_color_primary,
+    "secondary":  $guide_color_secondary,
+    "tertiary":   $guide_color_tertiary,
+    "quaternary": $guide_color_quaternary,
+    "light":      $guide_color_light,
+    "dark":       $guide_color_dark,
+);

package/scss/maps/_index.scss

@@ -0,0 +1 @@
+@forward "color";

package/scss/mixins/_device.scss

@@ -1,39 +1,77 @@
-// Copyright 2024 Scape Agency BV
+// ============================================================================
+// Poster
+// ============================================================================
 
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
+////
+/// 
+/// Device Mixins Module
+/// ===========================================================================
+/// 
+/// @group Device
+/// @author Scape Agency
+/// @link https://unit.gl
+/// @since 0.1.0 initial release
+/// @todo None
+/// @access public
+/// 
+////
 
-// http://www.apache.org/licenses/LICENSE-2.0
-
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
 
+// ============================================================================
+// Use
+// ============================================================================
 
 @use "../variables" as *;
 
-/// Generalized Media Query Mixin
-/// Creates a media query based on device attributes defined in $devices map.
-/// @param $device - The key name of the device in the $devices map.
-/// Usage Example:
-/// @include device-media-query('iphone-6-7-8') {// Styles specific to iPhone 6, 7, 8}
-@mixin device-media-query($device) {
-    // Retrieve the device attributes from the map
+
+// ============================================================================
+// Mixins
+// ============================================================================
+
+
+/// 
+/// Creates a media query based on device attributes defined in the `$devices`
+/// map. The media query supports min-width, max-width, and pixel-ratio.
+/// 
+/// @name device_media_query
+/// @param {String} $device - The key name of the device in the $devices map.
+/// @content Styles to be applied within the media query.
+/// 
+/// @example scss - Usage
+///     @include device-media-query('iphone-6') {
+///         // Styles specific to iPhone 6
+///     }
+/// 
+@mixin device_media_query($device) {
+    // Retrieve the device attributes from the $devices map
     $attributes: map-get($devices, $device);
-    
+
+    // Validate that the device exists in the $devices map
+    @if $attributes == null {
+        @warn "Device `#{$device}` not found in $devices map.";
+        // @return;
+    }
+
     // Extract individual attributes with default fallbacks
-    $min-width: if(map-has-key($attributes, "min-width"), map-get($attributes, "min-width"), null);
-    $max-width: if(map-has-key($attributes, "max-width"), map-get($attributes, "max-width"), null);
-    $pixel-ratio: if(map-has-key($attributes, "pixel-ratio"), map-get($attributes, "pixel-ratio"), 1); // Default to 1
+    $min-width: map-get($attributes, "min-width");
+    $max-width: map-get($attributes, "max-width");
+    $pixel-ratio: map-get($attributes, "pixel-ratio", 1); // Default to 1
 
     // Construct the media query string
     $media-query: "only screen";
-    $media-query: if($min-width != null, $media-query + " and (min-device-width: #{$min-width})", $media-query);
-    $media-query: if($max-width != null, $media-query + " and (max-device-width: #{$max-width})", $media-query);
-    $media-query: if($pixel-ratio != 1, $media-query + " and (-webkit-device-pixel-ratio: #{$pixel-ratio})", $media-query);
+
+    @if $min-width != null {
+        $media-query: "#{$media-query} and (min-width: #{$min-width})";
+    }
+
+    @if $max-width != null {
+        $media-query: "#{$media-query} and (max-width: #{$max-width})";
+    }
+
+    @if $pixel-ratio != 1 {
+        $media-query: "#{$media-query} and (-webkit-device-pixel-ratio: #{$pixel-ratio})";
+        $media-query: "#{$media-query} and (min-resolution: #{($pixel-ratio * 96)}dpi)";
+    }
 
     // Apply the media query
     @media #{$media-query} {

package/scss/mixins/_display.scss

@@ -1,34 +1,53 @@
-// Copyright 2024 Scape Agency BV
-
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
+// ============================================================================
+// Poster
+// ============================================================================
 
-// http://www.apache.org/licenses/LICENSE-2.0
+////
+/// 
+/// Display Mixins Module
+/// ===========================================================================
+/// 
+/// These mixins provide a convenient way to apply styles based on device
+/// orientation and display characteristics such as aspect ratio and pixel
+/// density. They are essential for creating responsive designs that adapt
+/// seamlessly to different device configurations, especially on mobile
+/// devices.
+/// 
+/// @group Display
+/// @author Scape Agency
+/// @link https://unit.gl
+/// @since 0.1.0 initial release
+/// @todo None
+/// @access public
+/// 
+////
 
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
 
+// ============================================================================
+// Use
+// ============================================================================
 
 @use "../variables" as *;
 
 
-
-
-// Mixins for Media Queries Based on Device Orientation
 // ============================================================================
-// These mixins provide a convenient way to apply styles based on the orientation of the device.
-// Useful for responsive designs that need to adapt to landscape or portrait modes, especially on tablets and smartphones.
+// Mixins
+// ============================================================================
 
-/// Mixin for landscape orientation with optional breakpoint
-/// Use this mixin to apply styles when the device is in landscape mode.
-/// @param $min-width (optional) - The minimum width at which the styles should apply
-/// Example usage:
-/// @include orientation-landscape(1024px) { /* styles */ }
-@mixin orientation-landscape($min-width: null) {
+
+/// 
+/// Applies styles when the device is in landscape mode. An optional
+/// minimum width can be specified to target specific breakpoints.
+/// 
+/// @name display-orientation-landscape
+/// @param {Length} $min-width (optional) - The minimum width at which the styles should apply.
+/// 
+/// @example scss - Usage
+///     @include display-orientation-landscape(1024px) {
+///         // Styles for landscape orientation and min-width 1024px
+///     }
+/// 
+@mixin display_orientation_landscape($min-width: null) {
     @if $min-width {
         @media (orientation: landscape) and (min-width: $min-width) {
             @content;
@@ -40,12 +59,23 @@
     }
 }
 
+
+///
 /// Mixin for portrait orientation with optional breakpoint
-/// Use this mixin to apply styles when the device is in portrait mode.
-/// @param $min-width (optional) - The minimum width at which the styles should apply
-/// Example usage:
-/// @include orientation-portrait { /* styles */ }
-@mixin orientation-portrait($min-width: null) {
+/// ---------------------------------------------------------------------------
+/// 
+/// Applies styles when the device is in portrait mode. An optional
+/// minimum width can be specified to target specific breakpoints.
+/// 
+/// @name display-orientation-portrait
+/// @param {Length} $min-width (optional) - The minimum width at which the styles should apply.
+/// 
+/// @example scss - Usage
+///     @include display-orientation-portrait(768px) {
+///         // Styles for portrait orientation and min-width 768px
+///     }
+/// 
+@mixin display_orientation_portrait($min-width: null) {
     @if $min-width {
         @media (orientation: portrait) and (min-width: $min-width) {
             @content;
@@ -58,26 +88,58 @@
 }
 
 
-
+/// 
 /// Mixin for targeting specific aspect ratios
-/// @param $width - Width of the aspect ratio
-/// @param $height - Height of the aspect ratio
-// @mixin aspect-ratio($width, $height) {
-//     @media (aspect-ratio: #{$width}/#{$height}) {
-//         @content;
-//     }
-// }
-
-
+/// ---------------------------------------------------------------------------
+/// 
+/// Applies styles based on a specific aspect ratio. This mixin is 
+/// useful for targeting devices or elements that have a particular
+/// aspect ratio, ensuring that your design adapts perfectly to 
+/// screens of varying shapes and sizes.
+/// 
+/// @name aspect_ratio
+/// @param {Number} $width - The width component of the aspect ratio.
+/// @param {Number} $height - The height component of the aspect ratio.
+/// 
+/// @example scss - Basic Usage
+///   @include aspect_ratio(16, 9) {
+///     // Styles for devices with a 16:9 aspect ratio
+///     .video {
+///       max-width: 100%;
+///     }
+///   }
+/// 
+/// @example scss - Complex Usage
+///   // Apply styles for both 16:9 and 4:3 aspect ratios
+///   @include aspect_ratio(16, 9), aspect_ratio(4, 3) {
+///     // Styles for devices with either a 16:9 or 4:3 aspect ratio
+///     .content {
+///       padding: 20px;
+///     }
+///   }
+/// 
+@mixin aspect_ratio($width, $height) {
+    @media (aspect-ratio: #{$width} / #{$height}) {
+        @content;
+    }
+}
 
 
-// Mixin for High-Density (Retina) Displays
-// ============================================================================
-/// This mixin targets high-density displays like Retina screens.
-/// It covers various methods to detect high pixel density to ensure broad compatibility.
-/// Usage: 
-/// @include retina { /* styles for retina displays */ }
-@mixin retina {
+/// 
+/// Mixin for High-Density (Retina) Displays
+/// ---------------------------------------------------------------------------
+/// 
+/// Targets high-density displays, such as Retina screens, using various
+/// methods to ensure broad compatibility across devices.
+/// 
+/// @name display_retina
+/// 
+/// @example scss - Usage
+///   @include display-retina {
+///     // Styles for high-density displays
+///   }
+/// 
+@mixin display_retina {
     // Webkit-based browsers
     @media only screen and (-webkit-min-device-pixel-ratio: 2),
            // Standard way to target high-resolution displays