unit.gl 0.0.35 → 0.0.39

package/scss/mixins/_guide.scss

@@ -1,44 +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
+// ============================================================================
+// Poster
+// ============================================================================
 
-// http://www.apache.org/licenses/LICENSE-2.0
+////
+/// 
+/// Guide Mixins Module
+/// ===========================================================================
+/// 
+/// This module provides mixins for creating visual guides, such as grid
+/// overlays and baseline grids, to assist in design alignment and consistency.
+//
+/// @group Guide
+/// @author Scape Agency
+/// @link https://unit.gl
+/// @since 0.1.0 initial release
+/// @todo None
+/// @requires "../variables" - for accessing project-specific variables.
+/// @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 *;
 
+
 // ============================================================================
-// Utilities | Guides
+// Mixins
 // ============================================================================
 
-$guide_color: rgba(50, 50, 50, 0.25);
-$guide_color_2: rgba(178, 51, 170, 0.5);
 
+/// 
+/// Guide Mixin
+/// ---------------------------------------------------------------------------
+/// 
+/// Creates a full-page guide overlay with a high z-index to ensure 
+/// visibility over other elements.
+/// 
+/// @name guide
+/// 
+/// @example scss - Usage
+///   .guide {
+///     @include guide;
+///   }
+/// 
 @mixin guide {
     z-index: z("guides");
-    position: absolute;
-    height: 100%;
-    width: 100%;
-    margin: 0;
-    top:0;
-    left:0;
-    opacity: 100%;
-    // background-size: $baseline_04 $baseline_04;
-    pointer-events: none;
-}
-
-
-// Mixins for Guide Visualization
-// @mixin guide($z-index: z('guides')) {
-  @mixin guide($z-index: 9999) {
+// @mixin guide($z-index: 9999) {
+//     z-index: $z-index;
     position: absolute;
     top: 0;
     left: 0;
@@ -46,151 +58,172 @@ $guide_color_2: rgba(178, 51, 170, 0.5);
     height: 100%;
     margin: 0;
     pointer-events: none;
-    z-index: $z-index;
-  }
+    opacity: 100%;
+    // background-size: $baseline_04 $baseline_04;
+}
 
-.guide { @include guide; }
 
 
-@mixin guide_graph($size, $color: $guide_color) {
+/// 
+/// Guide Graph Mixin
+/// ---------------------------------------------------------------------------
+/// 
+/// Generates a grid overlay with customizable grid size and color,
+/// useful for ensuring consistent spacing and alignment in your designs.
+/// 
+/// @name guide_graph
+/// @param {Length} $size - The size of the grid cells.
+/// @param {Color} $color - The color of the grid lines. Defaults to `$guide_color`.
+/// 
+/// @example scss - Usage
+///     .guide_graph {
+///         @include guide_graph(10px, #ccc);
+///     }
+/// 
+@mixin guide_graph(
+    $size,
+    $color: $guide_color,
+) {
     @include guide;
     background-size: $size $size;
     background-image: repeating-linear-gradient(
-                        to bottom,
-                        $color 0 1px,
-                        transparent 1px 100%
-                      ),
-                      repeating-linear-gradient(
-                        to right,
-                        $color 0 1px,
-                        transparent 1px 100%
-                      );
-  }
-
-  @mixin guide_baseline($size, $color: cyan) {
+        to bottom,
+        $color 0 1px,
+        transparent 1px 100%
+    ),
+    repeating-linear-gradient(
+        to right,
+        $color 0 1px,
+        transparent 1px 100%
+    );
+}
+
+
+/// 
+/// Guide Baseline Mixin
+/// ---------------------------------------------------------------------------
+/// 
+/// Creates a baseline grid overlay, essential for maintaining 
+/// a consistent vertical rhythm across your designs.
+/// 
+/// @name guide_baseline
+/// @param {Length} $size - The height of the baseline grid.
+/// @param {Color} $color - The color of the baseline lines. Defaults to cyan.
+/// 
+/// @example scss - Usage
+///   .guide_baseline {
+///     @include guide_baseline(20px, cyan);
+///   }
+/// 
+@mixin guide_baseline(
+    $size,
+    $color: $guide_color,
+) {
     @include guide;
     background-size: 100% $size;
     background-image: repeating-linear-gradient(
-                        to bottom,
-                        $color 0 1px,
-                        transparent 1px 100%
-                      );
-  }
-// .guide_graph { @include guide_graph; }
-
-
-
-// @mixin guide_baseline {
-//     @include guide;
-//     // background: repeating-linear-gradient(#e66465, #e66465 20px, #9198e5 20px, #9198e5 25px);
-//     // background: repeating-linear-gradient(transparent, transparent 20px, transparent 20px, transparent 25px);
-//     // background-repeat: repeat-y;
-//     background-repeat: repeat;
-
-//     background-size: map-get($baseline, 4) map-get($baseline, 4);
-//     @include guide;
-//     background-image:
-//         repeating-linear-gradient(cyan 0 1px, transparent 1px 100%);
-// }
+        to bottom,
+        $color 0 1px,
+        transparent 1px 100%
+    );
+}
 
 
-  
-  @mixin baseline-grid($column-width, $baseline-height, $column-color: rgba(200, 0, 0, 0.2), $baseline-color: rgba(56, 255, 255, 0.8)) {
+///
+/// Baseline Grid Mixin
+/// ---------------------------------------------------------------------------
+/// 
+/// Provides a customizable baseline grid overlay with both vertical
+/// and horizontal grid lines, useful for designing layouts with consistent
+/// column widths and baseline spacing.
+/// 
+/// @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).
+/// 
+/// @example scss - Usage
+///   .guide_baseline {
+///     @include guide_baseline(60px, 20px);
+///   }
+/// 
+@mixin guide_baseline(
+    $column_width,
+    $baseline_height,
+    $column_color: rgba(200, 0, 0, 0.2),
+    $baseline_color: $guide_color,
+) {
     background-image: linear-gradient(
-                        to right,
-                        $column-color 0 $column-width,
-                        transparent $column-width transparent
-                      ),
-                      linear-gradient(
-                        to bottom,
-                        transparent calc(100% - 1px),
-                        $baseline-color 100%
-                      );
-    background-size: $column-width 100%, 100% $baseline-height;
-  }
-
-
-html {
-    // @include guide_graph(calc(16*$q));
-    // @include guide_baseline($line_height_base);
+        to right,
+        $column_color 0 $column_width,
+        transparent $column_width transparent
+    ),
+    linear-gradient(
+        to bottom,
+        transparent calc(100% - 1px),
+        $baseline_color 100%
+    );
+    background-size: $column_width 100%, 100% $baseline_height;
 }
 
-.guide_graph {
-  @include guide_graph($rhythm_base);
 
+///
+/// Centered Guide Mixin
+/// ---------------------------------------------------------------------------
+/// 
+/// Creates a centered guide box useful for ensuring elements are
+/// aligned to the center of the viewport.
+/// 
+/// @name guide_centered
+/// @param {Length} $width - The width of the centered guide box.
+/// @param {Length} $height - The height of the centered guide box.
+/// @param {Color} $color - The color of the guide box border. Defaults to red.
+/// 
+/// @example scss - Usage
+///   .guide_centered {
+///     @include guide_centered(100px, 100px, red);
+///   }
+/// 
+@mixin guide_centered(
+    $width,
+    $height,
+    $color: red
+) {
+    @include guide;
+    width: $width;
+    height: $height;
+    top: 50%;
+    left: 50%;
+    transform: translate(-50%, -50%);
+    border: 2px solid $color;
 }
 
 
-.guide_baseline {
-  @include guide_baseline($line_height_base);
-
+/// 
+/// Margin Guide Mixin
+/// ---------------------------------------------------------------------------
+/// 
+/// Visualizes the margins around content, helping to ensure
+/// consistent spacing.
+/// 
+/// @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).
+/// 
+/// @example scss - Usage
+///     .guide_margin {
+///         @include guide_margin(20px, rgba(0, 255, 0, 0.1));
+///     }
+/// 
+@mixin guide_margin(
+    $margin,
+    $color: rgba(0, 255, 0, 0.1)
+) {
+    @include guide;
+    top: $margin;
+    left: $margin;
+    right: $margin;
+    bottom: $margin;
+    background-color: $color;
 }
-
-// .guide_baseline { @include guide_baseline; }
-
-
-// .baseline-grid {
-//     @include guide;
-
-//         background-image:
-//     // -webkit-linear-gradient(0deg, rgba(200,0,0,.2) 40px, transparent 40px),
-//     -webkit-linear-gradient(top, rgba(0,0,0,0) 95%, rgba(56,255,255,.8) 100%);
-
-
-//         background-image:
-//         // -moz-linear-gradient(0deg, rgba(200,0,0,.2) 40px, transparent 40px),
-//         -moz-linear-gradient(top, rgba(0,0,0,0) 95%, rgba(56,255,255,.8) 100%);
-//         background-image:
-//         // -o-linear-gradient(0deg, rgba(200,0,0,.2) 40px, transparent 40px),
-//         -o-linear-gradient(top, rgba(0,0,0,0) 95%, rgba(56,255,255,.8) 100%);
-
-//         background-size: 100% 100%, 100% 100%;
-//         // background-size: 60px 100%, 100% 22px;
-//         // background-position: 10px 0px;
-// }
-
-
-
-// // .guide_graph {
-// //   @include guide;
-// //   background-image:
-// //     repeating-linear-gradient(#ccc 0 1px, transparent 1px 100%),
-// //     repeating-linear-gradient(90deg, #ccc 0 1px, transparent 1px 100%);
-// //   }
-
-// // .guide_baseline {
-// //   @include guide;
-// //   background-image:
-// //     repeating-linear-gradient(cyan 0 2px, transparent 2px 100%);
-// // }
-
-// .page {
-//     border: $q*2 solid red;
-// }
-
-
-// $body-width: 960px;
-// $baseline: 22px;
-// @mixin baseline-grid {
-// 	$columns: 16;
-// 	$column-color: rgba(200,0,0,.2);
-// 	$baseline-color: rgba(56,255,255,.8);
-	
-// 	// These are all automatically calculated
-// 	$gutter-width: 20px;  // Change if you like
-// 	$gutters: ($columns - 1);
-// 	$column-width: calc($body-width / $columns);
-	
-// 	background-image: -webkit-linear-gradient(0deg, $column-color $column-width, transparent $gutter-width),
-// 							-webkit-linear-gradient(top, rgba(0,0,0,0) 95%, $baseline-color 100%);
-// 	background-image: -moz-linear-gradient(0deg, $column-color $column-width, transparent $gutter-width),
-// 							-moz-linear-gradient(top, rgba(0,0,0,0) 95%, $baseline-color 100%);
-// 	background-image: -o-linear-gradient(0deg, $column-color $column-width, transparent $gutter-width),
-// 							-o-linear-gradient(top, rgba(0,0,0,0) 95%, $baseline-color 100%);
-// 	background-size: ($column-width + $gutter-width) 100%, 100% $baseline;
-// 	background-position: 10px 0px; // Use to offset and center your grid
-// }
-
-// // Example call
-// .baseline-grid {
-// }