unit.gl 0.1.13 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unit.gl",
-  "version": "0.1.13",
+  "version": "0.2.3",
   "description": "Dynamic Layout Engine.",
   "keywords": [
     "unit.gl",

package/scss/functions/_layer.scss

@@ -15,6 +15,7 @@
 // ============================================================================
 // Use
 // ============================================================================
+@use "sass:map";
 
 // ============================================================================
 // Functions
@@ -32,8 +33,20 @@
 /// @return {Number | Null} - The z-index value associated with the layer,
 /// or null if not found.
 ///
+/// @example scss - Usage
+///   // Define layers map (typically in variables)
+///   $layers: (
+///     "base": 1,
+///     "modal": 1000,
+///     "guides": 9999
+///   );
+///
+///   .modal {
+///     z-index: z("modal");
+///   }
+///
 @function z($layer) {
-    @if not map-has-key($layers, $layer) {
+    @if not map.has-key($layers, $layer) {
         @warn "Layer `#{$layer}` not found in the $layers map. z-index property omitted.";
         @return null;
     }

package/scss/functions/_ratio.scss

@@ -20,6 +20,7 @@
 // ============================================================================
 // Use
 // ============================================================================
+@use "sass:math";
 
 // ============================================================================
 // Functions
@@ -53,7 +54,7 @@
     $golden-ratio: 1.618;
 
     // Validate the input size
-    @if not unitless($size) and type-of($size) != "number" {
+    @if not math.is-unitless($size) and type-of($size) != "number" {
         @error "The size parameter must be a valid number or unitless value.";
     }
 
@@ -63,5 +64,5 @@
     }
 
     // Return the size scaled by the golden ratio raised to the increment
-    @return $size * pow($golden-ratio, $increment);
+    @return $size * math.pow($golden-ratio, $increment);
 }

package/scss/functions/_scale.scss

@@ -20,6 +20,7 @@
 // ============================================================================
 // Use
 // ============================================================================
+@use "sass:math";
 
 // ============================================================================
 // Functions
@@ -41,13 +42,19 @@
 /// olden Ratio (1.618).
 /// @return {Number} - The calculated value based on the modular scale.
 ///
+/// @example scss - Usage
+///   // Font sizing using a modular scale
+///   h1 { font-size: modular_scale(3, 1rem, 1.25); }
+///   h2 { font-size: modular_scale(2, 1rem, 1.25); }
+///   p  { margin-bottom: modular_scale(1, 1rem, 1.25); }
+///
 @function modular_scale($increment: 1, $base: 1em, $ratio: 1.618) {
     // Validate inputs
     @if type-of($increment) != "number" {
         @error "Step must be a number.";
     }
 
-    @if type-of($base) != "number" and not unitless($base) {
+    @if type-of($base) != "number" and not math.is-unitless($base) {
         @error "Base must be a number with or without units.";
     }
 
@@ -56,5 +63,5 @@
     }
 
     // Calculate the modular scale value
-    @return $base * pow($ratio, $increment);
+    @return $base * math.pow($ratio, $increment);
 }

package/scss/functions/_sequence.scss

@@ -20,6 +20,7 @@
 // ============================================================================
 // Use
 // ============================================================================
+@use "sass:math";
 
 // ============================================================================
 // Functions
@@ -132,7 +133,7 @@
 /// @return {Number} - The nth Catalan number.
 ///
 @function sequence_catalan($n) {
-    @return factorial(2 * $n) / (factorial($n + 1) * factorial($n));
+    @return math.div(factorial(2 * $n), (factorial($n + 1) * factorial($n)));
 }
 
 ///
@@ -151,7 +152,7 @@
         @warn "Index #{$n} is not valid for the harmonic series.";
         @return null;
     }
-    @return 1 / $n;
+    @return math.div(1, $n);
 }
 
 ///
@@ -171,7 +172,7 @@
         @warn "Negative index #{$n} is not valid for the geometric series.";
         @return null;
     }
-    @return pow(2, $n - 1);
+    @return math.pow(2, $n - 1);
 }
 
 ///
@@ -213,7 +214,7 @@
         @warn "Index #{$n} is not valid for the triangular series.";
         @return null;
     }
-    @return $n * ($n + 1) / 2;
+    @return math.div($n * ($n + 1), 2);
 }
 
 ///
@@ -252,7 +253,7 @@
         @warn "Index #{$n} is not valid for the pentagonal series.";
         @return null;
     }
-    @return (3 * $n * $n - $n) / 2;
+    @return math.div((3 * $n * $n - $n), 2);
 }
 
 ///

package/scss/functions/math/_arithmetic.scss

@@ -23,6 +23,7 @@
 // ============================================================================
 // Use
 // ============================================================================
+@use "sass:math";
 
 // ============================================================================
 // Functions
@@ -39,6 +40,7 @@
 /// units, they must be the same unit; otherwise, a warning is issued and
 /// `null` is returned.
 ///
+/// @name add
 /// @param {Number} $value1 - The first value, which may or may not include
 /// units.
 /// @param {Number} $value2 - The second value, which may or may not include
@@ -47,13 +49,13 @@
 /// incompatible.
 ///
 @function add($value1, $value2) {
-    @if unitless($value1) and unitless($value2) {
+    @if math.is-unitless($value1) and math.is-unitless($value2) {
         @return $value1 + $value2;
-    } @else if unitless($value1) {
-        @return $value1 + unit-strip($value2);
-    } @else if unitless($value2) {
-        @return unit-strip($value1) + $value2;
-    } @else if unit($value1) == unit($value2) {
+    } @else if math.is-unitless($value1) {
+        @return $value1 + unit_strip($value2);
+    } @else if math.is-unitless($value2) {
+        @return unit_strip($value1) + $value2;
+    } @else if math.unit($value1) == math.unit($value2) {
         @return $value1 + $value2;
     } @else {
         @warn "Cannot add values with different units: #{$value1} and #{$value2}";
@@ -72,6 +74,7 @@
 /// units, they must be the same unit; otherwise, a warning is issued and
 /// `null` is returned.
 ///
+/// @name subtract
 /// @param {Number} $value1 - The first value, which may or may not include
 /// units.
 /// @param {Number} $value2 - The second value, which may or may not include
@@ -80,13 +83,13 @@
 /// units are incompatible.
 ///
 @function subtract($value1, $value2) {
-    @if unitless($value1) and unitless($value2) {
+    @if math.is-unitless($value1) and math.is-unitless($value2) {
         @return $value1 - $value2;
-    } @else if unitless($value1) {
-        @return $value1 - unit-strip($value2);
-    } @else if unitless($value2) {
-        @return unit-strip($value1) - $value2;
-    } @else if unit($value1) == unit($value2) {
+    } @else if math.is-unitless($value1) {
+        @return $value1 - unit_strip($value2);
+    } @else if math.is-unitless($value2) {
+        @return unit_strip($value1) - $value2;
+    } @else if math.unit($value1) == math.unit($value2) {
         @return $value1 - $value2;
     } @else {
         @warn "Cannot subtract values with different units: #{$value1} and #{$value2}";

package/scss/functions/unit/_unit_conversion.scss

@@ -28,56 +28,108 @@ $base-font-size: 16px !default;
 /// Create functions to convert between different measurement units, such as
 /// pixels to rem, em to pixels, etc.
 
+@use "sass:math";
+
+///
+/// Converts pixels to rem units using a configurable base.
+///
+/// @name px_to_rem
+/// @param {Number} $size - Size in pixels.
+/// @param {Number} $base - Base pixel size to convert against (default: 16px).
+/// @return {Number} - Size expressed in rem.
 @function px_to_rem($size, $base: 16px) {
-    @return $size / $base * 1rem;
+    @return math.div($size, $base) * 1rem;
 }
 
+///
+/// Converts rem units to pixels using a configurable base.
+///
+/// @name rem_to_px
+/// @param {Number} $size - Size in rem.
+/// @param {Number} $base - Base pixel size to convert against (default: 16px).
+/// @return {Number} - Size expressed in pixels.
 @function rem_to_px($size, $base: 16px) {
     @return $size * $base;
 }
 
+///
+/// Converts `em` units to pixels using a context size.
+///
+/// @name em_to_px
+/// @param {Number} $size - Size in em.
+/// @param {Number} $context - Context pixel size (default: 16px).
+/// @return {Number} - Size expressed in pixels.
 @function em_to_px($size, $context: 16px) {
     @return $size * $context;
 }
 
+///
+/// Converts pixels to `em` units using a context size.
+///
+/// @name px_to_em
+/// @param {Number} $size - Size in pixels.
+/// @param {Number} $context - Context pixel size (default: 16px).
+/// @return {Number} - Size expressed in em.
 @function px_to_em($size, $context: 16px) {
-    @return $size / $context * 1em;
+    @return math.div($size, $context) * 1em;
 }
 
 /// Validate that the input is a pixel value
+///
+/// @name validate_px
+/// @param {Number} $value - Value to validate.
+/// @return {Number} - Returns the input when validation passes; throws otherwise.
 @function validate_px($value) {
-    @if unit($value) != "px" {
+    @if math.unit($value) != "px" {
         @error "Expected a pixel value, but got `#{$value}`.";
     }
     @return $value;
 }
 
 /// Convert pixels to rem
+///
+/// @name px_to_rem
+/// @param {Number} $size - Size in pixels.
+/// @return {Number} - Size expressed in rem.
 @function px_to_rem($size) {
     $validated_size: validate_px($size);
-    @return $validated_size / $base-font-size * 1rem;
+    @return math.div($validated_size, $base-font-size) * 1rem;
 }
 
 /// Convert rem to pixels
+///
+/// @name rem_to_px
+/// @param {Number} $size - Size in rem.
+/// @return {Number} - Size expressed in pixels.
 @function rem_to_px($size) {
-    @if unit($size) != "rem" {
+    @if math.unit($size) != "rem" {
         @error "Expected a rem value, but got `#{$size}`.";
     }
     @return $size * $base-font-size;
 }
 
 /// Convert em to pixels
+///
+/// @name em_to_px
+/// @param {Number} $size - Size in em.
+/// @param {Number} $context - Context pixel size.
+/// @return {Number} - Size expressed in pixels.
 @function em_to_px($size, $context: $base-font-size) {
     $validated_context: validate_px($context);
-    @if unit($size) != "em" {
+    @if math.unit($size) != "em" {
         @error "Expected an em value, but got `#{$size}`.";
     }
     @return $size * $validated_context;
 }
 
 /// Convert pixels to em
+///
+/// @name px_to_em
+/// @param {Number} $size - Size in pixels.
+/// @param {Number} $context - Context pixel size.
+/// @return {Number} - Size expressed in 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;
+    @return math.div($validated_size, $validated_context) * 1em;
 }

package/scss/functions/unit/_unit_functions.scss

@@ -75,10 +75,10 @@
 ///
 @function linear_interpolation($start, $end, $min, $max, $actual: 100vw) {
     // Validate parameters
-    @if unitless($min) == false and unit($min) != "px" {
+    @if math.is-unitless($min) == false and math.unit($min) != "px" {
         @error "Parameter `$min` must be unitless or in 'px'.";
     }
-    @if unitless($max) == false and unit($max) != "px" {
+    @if math.is-unitless($max) == false and math.unit($max) != "px" {
         @error "Parameter `$max` must be unitless or in 'px'.";
     }
     @if $max <= $min {
@@ -86,7 +86,7 @@
     }
 
     // Convert all values to a common unit for calculation
-    $unit: 1#{unit($start)};
+    $unit: 1#{math.unit($start)};
 
     // Convert coordinate values to unitless for calculations
     $x0: #{unit_strip($min)};

package/scss/mixins/_display.scss

@@ -26,7 +26,6 @@
 @use "../variables" as *;
 @use "../maps" as *;
 
-
 // ============================================================================
 // Mixins
 // ============================================================================
@@ -34,6 +33,8 @@
 ///
 /// Applies styles in landscape orientation, optionally above a min-width.
 ///
+/// @name display_orientation_landscape
+///
 /// @param {Length|null} $min-width - Optional breakpoint to combine with orientation
 ///
 /// @example scss
@@ -56,6 +57,8 @@
 ///
 /// Applies styles in portrait orientation, optionally above a min-width.
 ///
+/// @name display_orientation_portrait
+///
 /// @param {Length|null} $min-width - Optional breakpoint to combine with orientation
 ///
 /// @example scss
@@ -79,6 +82,8 @@
 /// Applies styles on high-density (Retina) displays.
 /// Targets modern and older syntax for broad support.
 ///
+/// @name display_retina
+///
 /// @example scss
 ///   @include display_retina {
 ///     // high-resolution styles
@@ -95,6 +100,8 @@
 ///
 /// Applies styles when the screen matches a specific aspect ratio.
 ///
+/// @name display_ratio
+///
 /// @param {Number} $width - The horizontal component of the aspect ratio
 /// @param {Number} $height - The vertical component of the aspect ratio
 ///
@@ -104,7 +111,7 @@
 ///   }
 ///
 @mixin display_ratio($width, $height) {
-    @media (aspect-ratio: #{ $width / $height }) {
+    @media (aspect-ratio: #{ $width } / #{ $height }) {
         @content;
     }
 }

package/scss/mixins/_guide.scss

@@ -22,11 +22,35 @@
 
 @use "sass:map";
 @use "sass:meta";
+@use "sass:color";
 
 @use "../functions" as *;
 @use "../variables" as *;
 @use "../maps" as *;
 
+// ----------------------------------------------------------------------------
+// Helpers
+// ----------------------------------------------------------------------------
+
+///
+/// Guide Z-Index Helper
+/// ---------------------------------------------------------------------------
+///
+/// Resolves the z-index for guide overlays. If the project defines a `z()`
+/// function and a `"guides"` layer in `$layers`, it uses that value; otherwise
+/// it falls back to `9999`.
+///
+/// @name guide-z-index
+/// @return {Number} - The resolved z-index for guide elements.
+///
+@function guide-z-index() {
+    $value: 9999;
+    @if meta.function-exists("z") {
+        $value: z("guides");
+    }
+    @return $value;
+}
+
 // ============================================================================
 // Mixins
 // ============================================================================
@@ -46,7 +70,7 @@
 ///   }
 ///
 @mixin guide {
-    z-index: if(meta.function-exists("z"), z("guides"), 9999);
+    z-index: guide-z-index();
     position: absolute;
     top: 0;
     left: 0;
@@ -59,6 +83,19 @@
     background-attachment: local;
 }
 
+///
+/// Guide Layer Mixin
+/// ---------------------------------------------------------------------------
+///
+/// Provides a single guide layer that can be toggled via the `.active` class.
+/// Useful for composing multiple overlay layers and enabling them selectively.
+///
+/// @name guide--layer
+/// @example scss - Usage
+///   .guide-layer {
+///     @include guide--layer;
+///   }
+///
 @mixin guide--layer {
     display: none;
     position: absolute;
@@ -67,7 +104,7 @@
     width: 100%;
     min-height: 100vh;
     pointer-events: none;
-    z-index: if(meta.function-exists("z"), z("guides"), 9999);
+    z-index: guide-z-index();
     &.active {
         display: block !important;
     }
@@ -127,7 +164,8 @@
     background-repeat: repeat;
     background-size: $column_width $row_height;
 
-    background-image: repeating-linear-gradient(
+    background-image:
+        repeating-linear-gradient(
             to right,
             $column_color 0,
             $column_color 1px,
@@ -143,6 +181,25 @@
         );
 }
 
+///
+/// Centered Graph Guide Mixin
+/// ---------------------------------------------------------------------------
+///
+/// Renders a grid overlay centered in the viewport by offsetting the grid so
+/// the middle column aligns with the viewport center.
+///
+/// @name guide--graph_centered
+/// @param {Number} $columns - Number of columns in the grid.
+/// @param {Length} $column_width - Width of each column.
+/// @param {Length} $row_height - Height of each row.
+/// @param {Color} $column_color - Color of the column lines. Defaults to `$guide--graph_primary`.
+/// @param {Color} $baseline_color - Color of the baseline lines. Defaults to `$guide--graph_primary`.
+///
+/// @example scss - Usage
+///   .guide--graph-centered {
+///     @include guide--graph_centered(12, 60px, 20px);
+///   }
+///
 @mixin guide--graph_centered(
     $columns: 12,
     $column_width: baseline(4),
@@ -161,7 +218,8 @@
 
     background-position: $half_offset 0;
 
-    background-image: repeating-linear-gradient(
+    background-image:
+        repeating-linear-gradient(
             to right,
             $column_color 0,
             $column_color 1px,
@@ -216,8 +274,8 @@
 /// @name guide--baseline
 /// @param {Length} $column_width - The width of each column in the grid.
 /// @param {Length} $baseline_height - The height of each baseline.
-/// @param {Color} $column_color - The color of the column lines. Defaults to rgba(200, 0, 0, 0.2).
-/// @param {Color} $baseline_color - The color of the baseline lines. Defaults to rgba(56, 255, 255, 0.8).
+/// @param {Color} $column_color - The color of the column lines. Defaults to `color.change(rgb(200, 0, 0), $alpha: 0.2)`.
+/// @param {Color} $baseline_color - The color of the baseline lines. Defaults to `$guide--color`.
 ///
 /// @example scss - Usage
 ///   .guide--baseline {
@@ -227,10 +285,11 @@
 @mixin grid_baseline(
     $column_width,
     $baseline_height,
-    $column_color: rgba(200, 0, 0, 0.2),
+    $column_color: color.change(rgb(200, 0, 0), $alpha: 0.2),
     $baseline_color: $guide--color
 ) {
-    background-image: linear-gradient(
+    background-image:
+        linear-gradient(
             to right,
             $column_color 0 $column_width,
             transparent $column_width transparent
@@ -254,14 +313,17 @@
 ///
 /// @name guide--margin
 /// @param {Length} $margin - The size of the margin to visualize.
-/// @param {Color} $color - The color of the margin area. Defaults to rgba(0, 255, 0, 0.1).
+/// @param {Color} $color - The color of the margin area. Defaults to `color.change(rgb(0, 255, 0), $alpha: 0.1)`.
 ///
 /// @example scss - Usage
 ///     .guide--margin {
-///         @include guide--margin(20px, rgba(0, 255, 0, 0.1));
+///         @include guide--margin(20px, color.change(rgb(0, 255, 0), $alpha: 0.1));
 ///     }
 ///
-@mixin guide--margin($margin, $color: rgba(0, 255, 0, 0.1)) {
+@mixin guide--margin(
+    $margin,
+    $color: color.change(rgb(0, 255, 0), $alpha: 0.1)
+) {
     @include guide;
     top: $margin;
     left: $margin;

package/scss/mixins/_paper.scss

@@ -19,6 +19,7 @@
 // ============================================================================
 // Use
 // ============================================================================
+@use "sass:map";
 
 @use "../functions" as *;
 @use "../variables" as *;
@@ -41,11 +42,11 @@
 ///   }
 ///
 @mixin set_paper_size($size) {
-    @if map-has-key($paper-sizes, $size) {
+    @if map.has-key($paper-sizes, $size) {
         $size-map: map.get($paper-sizes, $size);
         width: map.get($size-map, width);
         height: map.get($size-map, height);
     } @else {
-        @warn "Invalid paper size: #{$size}. Available sizes are: #{map-keys($paper-sizes)}.";
+        @warn "Invalid paper size: #{$size}. Available sizes are: #{map.keys($paper-sizes)}.";
     }
 }

package/scss/mixins/_view.scss

@@ -21,6 +21,7 @@
 // ============================================================================
 // Use
 // ============================================================================
+@use "sass:map";
 
 @use "../variables" as *;
 
@@ -43,7 +44,7 @@
 ///   }
 ///
 @mixin breakpoint($size) {
-    @if map-has-key($breakpoints, $size) {
+    @if map.has-key($breakpoints, $size) {
         @media (min-width: map.get($breakpoints, $size)) {
             @content;
         }

package/scss/tags/_global.scss

@@ -1,3 +1,21 @@
+////
+///
+/// Global Tags Module
+/// =========================================================================
+///
+/// Base element resets and global defaults for `html`, `body`, and
+/// universal selectors. Provides consistent box-sizing, text adjustments,
+/// and baseline resets that apply across the application.
+///
+/// @group Tags
+/// @author Scape Agency
+/// @link https://unit.gl
+/// @since 0.1.0 initial release
+/// @todo None
+/// @access public
+///
+////
+
 // Base | Body
 // ============================================================================
 

package/scss/test.scss

@@ -0,0 +1,17 @@
+////
+///
+/// Test Styles Module
+/// =========================================================================
+///
+/// Placeholder for ad-hoc style tests and experiments. Not included in
+/// production builds; used locally to validate mixins, functions, and
+/// variables during development.
+///
+/// @group Dev
+/// @author Scape Agency
+/// @link https://unit.gl
+/// @since 0.1.0 initial release
+/// @todo Replace with targeted component/style demos when needed
+/// @access private
+///
+////

package/scss/variables/_color.scss

@@ -19,6 +19,7 @@
 // ============================================================================
 // Use
 // ============================================================================
+@use "sass:color";
 
 // ============================================================================
 // Variables
@@ -29,10 +30,9 @@ $guide--baseline_secondary: rgb(125, 181, 203);
 
 $guide--color: rgb(0, 200, 255);
 
-$guide--graph_primary: rgba(111, 124, 126, 0.483);
-
-$guide--bleed_primary: rgba(178, 51, 170, 0.5);
+$guide--graph_primary: color.change(rgb(111, 124, 126), $alpha: 0.483);
 
+$guide--bleed_primary: color.change(rgb(178, 51, 170), $alpha: 0.5);
 
 ///
 /// Primary Guide Color
@@ -40,7 +40,7 @@ $guide--bleed_primary: rgba(178, 51, 170, 0.5);
 ///
 /// Neutral gray for general guide overlays
 ///
-$guide--color_primary: rgba(50, 50, 50, 0.25);
+$guide--color_primary: color.change(rgb(50, 50, 50), $alpha: 0.25);
 
 ///
 /// Secondary Guide Color
@@ -48,7 +48,7 @@ $guide--color_primary: rgba(50, 50, 50, 0.25);
 ///
 /// Highlight color for key guides or emphasis
 ///
-$guide--color_secondary: rgba(178, 51, 170, 0.5);
+$guide--color_secondary: color.change(rgb(178, 51, 170), $alpha: 0.5);
 
 ///
 /// Tertiary Guide Color (Extended)
@@ -56,7 +56,7 @@ $guide--color_secondary: rgba(178, 51, 170, 0.5);
 ///
 /// A warm orange for alternate guide markings
 ///
-$guide--color_tertiary: rgba(255, 102, 0, 0.3);
+$guide--color_tertiary: color.change(rgb(255, 102, 0), $alpha: 0.3);
 
 ///
 /// Quaternary Guide Color (Extended)
@@ -64,7 +64,7 @@ $guide--color_tertiary: rgba(255, 102, 0, 0.3);
 ///
 /// A cool blue for additional grid or alignment lines
 ///
-$guide--color_quaternary: rgba(0, 102, 255, 0.3);
+$guide--color_quaternary: color.change(rgb(0, 102, 255), $alpha: 0.3);
 
 ///
 /// Light Guide Color (Extended)
@@ -72,7 +72,7 @@ $guide--color_quaternary: rgba(0, 102, 255, 0.3);
 ///
 /// Light color for subtle or background guides
 ///
-$guide--color_light: rgba(255, 255, 255, 0.2);
+$guide--color_light: color.change(rgb(255, 255, 255), $alpha: 0.2);
 
 ///
 /// Dark Guide Color (Extended)
@@ -80,4 +80,4 @@ $guide--color_light: rgba(255, 255, 255, 0.2);
 ///
 /// Dark color for use on lighter backgrounds
 ///
-$guide--color_dark: rgba(0, 0, 0, 0.2);
+$guide--color_dark: color.change(rgb(0, 0, 0), $alpha: 0.2);

package/scss/variables/_guide.scss

@@ -0,0 +1,17 @@
+////
+///
+/// Guide Variables Module
+/// =========================================================================
+///
+/// Reserved for variables related to visual guides (grid overlays,
+/// baselines, alignment helpers). Centralizing guide-specific variables
+/// here keeps concerns separated from general color or layout variables.
+///
+/// @group Variables
+/// @author Scape Agency
+/// @link https://unit.gl
+/// @since 0.1.0 initial release
+/// @todo Populate with guide-specific tokens as they are formalized
+/// @access public
+///
+////