unit.gl 0.0.35 → 0.0.39

package/scss/mixins/_helper.scss

@@ -1,105 +1,340 @@
-// 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.
-
+// ============================================================================
+// Poster
+// ============================================================================
+
+////
+/// 
+/// Helper Mixins Module
+/// ===========================================================================
+/// 
+/// This module provides a collection of utility mixins for common CSS
+/// properties like width, height, font size, padding, margin, and border
+/// properties. These mixins leverage a `q()` function (presumably defined
+/// elsewhere) to standardize the application of units across the project,
+/// promoting consistency and scalability.
+/// 
+/// @group Helper
+/// @author Scape Agency
+/// @link https://unit.gl
+/// @since 0.1.0 initial release
+/// @todo None
+/// @access public
+/// 
+////
+
+
+// ============================================================================
+// Use
+// ============================================================================
 
 @use "../variables" as *;
 
 
+// ============================================================================
+// Mixins
+// ============================================================================
 
-// Dimensions
-// ----------------------------------------------------------------------------
 
-@mixin width($value) {
+// Dimensions
+// ============================================================================
+
+
+/// 
+/// Sets the width of an element using the provided value.
+/// 
+/// @name set_width
+/// @group Dimensions
+/// @param {Length} $value - The width value to apply.
+/// 
+/// @example scss - Usage
+///   .box {
+///     @include set_width(100px);
+///   }
+/// 
+@mixin set_width($value) {
     @include q($value, width);
 }
 
-@mixin height($value) {
+
+/// 
+/// Sets the height of an element using the provided value.
+/// 
+/// @name set_height
+/// @group Dimensions
+/// @param {Length} $value - The height value to apply.
+/// 
+/// @example scss - Usage
+///   .box {
+///     @include set_height(200px);
+///   }
+/// 
+@mixin set_height($value) {
     @include q($value, height);
 }
 
-
-// Typography
+// TYPOGRAPHY
 // ----------------------------------------------------------------------------
 
-@mixin font-size($value) {
+
+/// 
+/// Sets the font size of an element using the provided value.
+/// 
+/// @name set_font-size
+/// @group Typography
+/// @param {Length} $value - The font size value to apply.
+/// 
+/// @example scss - Usage
+///   .text {
+///     @include set_font-size(16px);
+///   }
+/// 
+@mixin set_font-size($value) {
     @include q($value, font-size);
 }
 
-@mixin line-height($value) {
-    @include q($value, line-height);
+
+/// 
+/// Sets the line height of an element using the provided value.
+/// 
+/// @name set_line_height
+/// @group Typography
+/// @param {Length} $value - The line height value to apply.
+/// 
+/// @example scss - Usage
+///   .text {
+///     @include set_line_height(1.5);
+///   }
+/// 
+@mixin set_line_height($value) {
+    @include q($value, line_height);
 }
 
-@mixin letter-spacing($value) {
+
+/// 
+/// Sets the letter spacing of an element using the provided value.
+/// @name set_letter-spacing
+/// 
+/// @group Typography
+/// @param {Length} $value - The letter spacing value to apply.
+/// 
+/// @example scss - Usage
+///   .text {
+///     @include set_letter-spacing(0.1em);
+///   }
+/// 
+@mixin set_letter-spacing($value) {
     @include q($value, letter-spacing);
 }
 
-
-// Border
+// BORDERS
 // ----------------------------------------------------------------------------
 
-@mixin border-width($value) {
-    @include q($value, border-width);
-}
 
-@mixin border-radius($value) {
-    @include q($value, border-radius);
+/// 
+/// Sets the border width of an element using the provided value.
+/// 
+/// @name set_border_width
+/// @group Borders
+/// @param {Length} $value - The border width value to apply.
+/// 
+/// @example scss - Usage
+///   .box {
+///     @include set_border_width(2px);
+///   }
+/// 
+@mixin set_border_width($value) {
+    @include q($value, border_width);
 }
 
 
-// Padding
+/// 
+/// Sets the border radius of an element using the provided value.
+/// 
+/// @name set_border_radius
+/// @group Borders
+/// @param {Length} $value - The border radius value to apply.
+/// 
+/// @example scss - Usage
+///   .box {
+///     @include set_border_radius(8px);
+///   }
+/// 
+@mixin set_border_radius($value) {
+    @include q($value, border_radius);
+}
+
+// PADDING
 // ----------------------------------------------------------------------------
 
-@mixin padding($value) {
+
+/// 
+/// Sets the padding of an element using the provided value.
+/// 
+/// @name set_padding
+/// @group Spacing
+/// @param {Length} $value - The padding value to apply.
+/// 
+/// @example scss - Usage
+///   .box {
+///     @include set_padding(10px);
+///   }
+/// 
+@mixin set_padding($value) {
     @include q($value, padding);
 }
 
-@mixin padding-top($value) {
-    @include q($value, padding-top);
-}
 
-@mixin padding-right($value) {
-    @include q($value, padding-right);
+/// 
+/// Sets the top padding of an element using the provided value.
+/// 
+/// @name set_padding_top
+/// @group Spacing
+/// @param {Length} $value - The padding_top value to apply.
+/// 
+/// @example scss - Usage
+///   .box {
+///     @include set_padding_top(10px);
+///   }
+/// 
+@mixin set_padding_top($value) {
+    @include q($value, padding_top);
 }
 
-@mixin padding-bottom($value) {
-    @include q($value, padding-bottom);
+
+/// 
+/// Sets the right padding of an element using the provided value.
+/// 
+/// @name set_padding_right
+/// @group Spacing
+/// @param {Length} $value - The padding_right value to apply.
+/// 
+/// @example scss - Usage
+///   .box {
+///     @include set_padding_right(10px);
+///   }
+/// 
+@mixin set_padding_right($value) {
+    @include q($value, padding_right);
 }
 
-@mixin padding-left($value) {
-    @include q($value, padding-left);
+
+/// 
+/// Sets the bottom padding of an element using the provided value.
+/// 
+/// @name set_padding_bottom
+/// @group Spacing
+/// @param {Length} $value - The padding_bottom value to apply.
+/// 
+/// @example scss - Usage
+///   .box {
+///     @include set_padding_bottom(10px);
+///   }
+/// 
+@mixin set_padding_bottom($value) {
+    @include q($value, padding_bottom);
 }
 
 
-// Margin
+/// 
+/// Sets the left padding of an element using the provided value.
+/// 
+/// @name set_padding_left
+/// @group Spacing
+/// @param {Length} $value - The padding_left value to apply.
+/// 
+/// @example scss - Usage
+///   .box {
+///     @include set_padding_left(10px);
+///   }
+/// 
+@mixin set_padding_left($value) {
+    @include q($value, padding_left);
+}
+
+// MARGIN
 // ----------------------------------------------------------------------------
 
-@mixin margin($value) {
+
+/// 
+/// Sets the margin of an element using the provided value.
+/// 
+/// @name set_margin
+/// @group Spacing
+/// @param {Length} $value - The margin value to apply.
+/// 
+/// @example scss - Usage
+///   .box {
+///     @include set_margin(10px);
+///   }
+/// 
+@mixin set_margin($value) {
     @include q($value, margin);
 }
 
-@mixin margin-top($value) {
-    @include q($value, margin-top);
+
+/// 
+/// Sets the top margin of an element using the provided value.
+/// 
+/// @name set_margin_top
+/// @group Spacing
+/// @param {Length} $value - The margin_top value to apply.
+/// 
+/// @example scss - Usage
+///   .box {
+///     @include set_margin_top(10px);
+///   }
+/// 
+@mixin set_margin_top($value) {
+    @include q($value, margin_top);
 }
 
-@mixin margin-right($value) {
-    @include q($value, margin-right);
+
+/// 
+/// Sets the right margin of an element using the provided value.
+/// 
+/// @name set_margin_right
+/// @group Spacing
+/// @param {Length} $value - The margin_right value to apply.
+/// 
+/// @example scss - Usage
+///   .box {
+///     @include set_margin_right(10px);
+///   }
+/// 
+@mixin set_margin_right($value) {
+    @include q($value, margin_right);
 }
 
-@mixin margin-bottom($value) {
-    @include q($value, margin-bottom);
+
+/// 
+/// Sets the bottom margin of an element using the provided value.
+/// 
+/// @name set_margin_bottom
+/// @group Spacing
+/// @param {Length} $value - The margin_bottom value to apply.
+/// 
+/// @example scss - Usage
+///   .box {
+///     @include set_margin_bottom(10px);
+///   }
+/// 
+@mixin set_margin_bottom($value) {
+    @include q($value, margin_bottom);
 }
 
-@mixin margin-left($value) {
-    @include q($value, margin-left);
+
+/// 
+/// Sets the left margin of an element using the provided value.
+/// 
+/// @name set_margin_left
+/// @group Spacing
+/// @param {Length} $value - The margin_left value to apply.
+/// 
+/// @example scss - Usage
+///     .box {
+///         @include set_margin_left(10px);
+///     }
+/// 
+@mixin set_margin_left($value) {
+    @include q($value, margin_left);
 }

package/scss/mixins/_index.scss

@@ -1,23 +1,56 @@
-// 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
+////
+/// 
+/// Mixins Module
+/// ===========================================================================
+/// 
+/// This file centralizes the forwarding of various SCSS partials/modules used
+/// across the project. By aggregating these forwards, it simplifies imports
+/// in other parts of the codebase, promoting better modularity and
+/// organization.
+/// 
+/// This module forwards several other modules to streamline imports
+/// and maintain a clean, modular structure. Each forwarded module contains 
+/// specific functionalities, from managing viewports to handling aspect
+/// ratios.
+///
+/// Forwarded Modules:
+/// - paper: Contains paper sizes and related utilities.
+/// - view: Manages viewport-specific variables, such as breakpoints.
+/// - ratio: Includes mixins and functions for aspect ratio calculations.
+/// - device: Device-specific configurations for responsive design.
+/// - display: Display-related settings and utilities, including typography.
+/// - guide: Utilities for creating visual guides and overlays.
+/// - helper: General helper functions and mixins for common tasks.
+/// 
+/// @group Mixins
+/// @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
+// ============================================================================
 
 
+// ============================================================================
+// Forward
+// ============================================================================
 
-@forward "paper";
-@forward "view";
-@forward "ratio";
-@forward "device";
-@forward "display";
-@forward "guide";
-@forward "helper";
+/// Forwarding modules for global access
+@forward "unit";
+@forward "paper";   // Handles paper sizes and related utilities
+@forward "view";    // Manages viewport and breakpoint variables
+@forward "ratio";   // Provides aspect ratio utilities
+@forward "device";  // Device-specific responsive configurations
+@forward "display"; // Typography and display settings
+@forward "guide";   // Visual guide and overlay utilities
+@forward "helper";  // General-purpose helper functions and mixins

package/scss/mixins/_paper.scss

@@ -1,35 +1,56 @@
-// 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
+// ============================================================================
+// Poster
+// ============================================================================
 
-// 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.
+////
+/// 
+/// Paper Mixins Module
+/// ===========================================================================
+/// 
+/// This module provides utilities for applying standard paper sizes to
+/// elements. The sizes are defined in the $paper-sizes map and can be applied
+/// using the `set-paper-size` mixin.
+/// 
+/// @group Paper
+/// @author Scape Agency
+/// @link https://unit.gl
+/// @since 0.1.0 initial release
+/// @todo None
+/// @access public
+/// 
+////
 
 
 // ============================================================================
-// Paper Module
+// Use
 // ============================================================================
 
 @use "../variables" as *;
 
-// Apply Function
+
 // ============================================================================
+// Mixins
+// ============================================================================
+
 
+/// 
+/// Applies the width and height of the specified paper size to the
+/// element. The paper sizes must be predefined in the $paper-sizes map.
+/// 
+/// @name set_paper_size
+/// @param {String} $size - The key representing the paper size in the $paper-sizes map.
+/// 
+/// @example scss - Usage
+///   .document {
+///     @include set-paper-size('A4');
+///   }
+/// 
 @mixin set_paper_size($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}.";
+        @warn "Invalid paper size: #{$size}. Available sizes are: #{map-keys($paper-sizes)}.";
     }
 }
-
-

package/scss/mixins/_ratio.scss

@@ -1,24 +1,42 @@
-// 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
+////
+/// 
+/// Ratio Mixins Module
+/// ===========================================================================
+/// 
+/// This module provides mixins for creating aspect ratio containers.
+/// These containers maintain a specific width-to-height ratio, ensuring
+/// that elements scale proportionally across different screen sizes.
+///
+/// There are two approaches provided: one using the `aspect-ratio` CSS
+/// property, and another using padding percentages for broader browser
+/// support.
+/// 
+/// @group Ratio
+/// @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 *;
 
 
 // ============================================================================
-// Layout | Ratio
+// Mixins
 // ============================================================================
 
+
 // Aspect Ratio Box:
 // Creates a container with a specific aspect ratio.
 // @mixin aspect-ratio($width, $height) {
@@ -41,6 +59,7 @@
 //   @include aspect-ratio(16, 9);
 // }
 
+
 @mixin ratio ($val01, $val02) {
     aspect-ratio: calc($val01 / $val02);
     width: 100%;
@@ -79,8 +98,6 @@
 .ratio_16x10 { @include ratio_16x10; }
 
 
-// . 
-// ----------------------------------------------------------------------------
 
 @mixin ratio_p ($val01) {
     padding-bottom: $val01;