unit.gl 0.0.35 → 0.0.39

package/scss/variables/_device.scss

@@ -1,77 +1,167 @@
-// 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 Variables Module
+/// ===========================================================================
+///
+/// This file defines a map of device attributes, including screen dimensions
+/// and pixel ratios, for a variety of devices. This map is structured for
+/// easy access and modification, ensuring responsive designs that cater to
+/// a wide range of devices.
+/// 
+/// @group Color
+/// @author Scape Agency
+/// @link https://unit.gl
+/// @since 0.1.0 initial release
+/// @todo None
+/// @access public
+/// 
+/// @example scss - Usage Example
+///   @media (min-width: map-get($devices, "iphone-x")["min-width"]) {
+///       // Styles specific to iPhone X
+///   }
+/// 
+////
 
-// 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
+// ============================================================================
 
 
-// Device Attribute Map
 // ============================================================================
+// Variables
+// ============================================================================
+
+
+/// 
+/// Device Attribute Map
+/// ---------------------------------------------------------------------------
+/// 
+/// A map containing attributes for various devices. Each entry includes the
+/// device's minimum and maximum screen widths, as well as the pixel ratio.
+/// The map is divided into categories for smartphones, tablets, and
+/// desktops/laptops.
+/// 
+/// This map contains attributes for various devices, including screen
+/// dimensions and pixel ratios. It is structured for easy access and
+/// modification, ensuring responsive designs that cater to a wide range
+/// of devices.
+///
+/// @type Map
+/// @access public
+/// @property iPhones - iPhones with varying screen sizes and pixel densities.
+/// 
+/// @example scss - Usage Example
+///     @media (min-width: map-get($devices, "iphone-x")["min-width"]) {
+///         // Styles specific to iPhone X
+///     }
+///
 $devices: (
+
+    // Phones
+    // ========================================================================
+
     // iPhones
     // ------------------------------------------------------------------------
-    "iphone-5":         ("min-width":  320px, "max-width":  568px, "pixel-ratio": 2),
-    "iphone-6-7-8":     ("min-width":  375px, "max-width":  667px, "pixel-ratio": 2),
-    "iphone-x":         ("min-width":  375px, "max-width":  812px, "pixel-ratio": 3),
-    "iphone-11":        ("min-width":  414px, "max-width":  896px, "pixel-ratio": 2),
-    "iphone-12":        ("min-width":  390px, "max-width":  844px, "pixel-ratio": 3),
-    "iphone-13":        ("min-width":  428px, "max-width":  926px, "pixel-ratio": 3),
+
     
-    // iPads
-    // ------------------------------------------------------------------------
-    "ipad":             ("min-width":  768px, "max-width": 1024px, "pixel-ratio": 2),
-    "ipad-pro":         ("min-width": 1024px, "max-width": 1366px, "pixel-ratio": 2),
-    "ipad-mini":        ("min-width":  768px, "max-width": 1024px, "pixel-ratio": 2),
-    "ipad-air":         ("min-width":  820px, "max-width": 1180px, "pixel-ratio": 2),
+    /// iPhones
+    /// iPhones with varying screen sizes and pixel densities.
+    "iphone-5":         ("min-width": 320px,  "max-width": 568px,  "pixel-ratio": 2.0),
+    "iphone-6":         ("min-width": 375px,  "max-width": 667px,  "pixel-ratio": 2.0),
+    "iphone-7":         ("min-width": 375px,  "max-width": 667px,  "pixel-ratio": 2.0),
+    "iphone-8":         ("min-width": 375px,  "max-width": 667px,  "pixel-ratio": 2.0),
+    "iphone-x":         ("min-width": 375px,  "max-width": 812px,  "pixel-ratio": 3.0),
+    "iphone-11":        ("min-width": 414px,  "max-width": 896px,  "pixel-ratio": 2.0),
+    "iphone-12":        ("min-width": 390px,  "max-width": 844px,  "pixel-ratio": 3.0),
+    "iphone-13":        ("min-width": 428px,  "max-width": 926px,  "pixel-ratio": 3.0),
 
     // Samsung Galaxy
     // ------------------------------------------------------------------------
-    "samsung-s10":      ("min-width":  360px, "max-width":  760px, "pixel-ratio": 3),
-    "samsung-s20":      ("min-width":  320px, "max-width":  720px, "pixel-ratio": 4),
-    "samsung-s21":      ("min-width":  320px, "max-width":  780px, "pixel-ratio": 3),
+    
+    /// iPhones
+    /// iPhones with varying screen sizes and pixel densities.
+    "samsung-s10":      ("min-width": 360px,  "max-width": 760px,  "pixel-ratio": 3.0),
+    "samsung-s20":      ("min-width": 320px,  "max-width": 720px,  "pixel-ratio": 4.0),
+    "samsung-s21":      ("min-width": 320px,  "max-width": 780px,  "pixel-ratio": 3.0),
+
+    // Samsung Galaxy Fold
+    // ------------------------------------------------------------------------
+    
+    /// Samsung Galaxy Fold
+    /// Samsung Galaxy Fold devices with foldable screens.
+    "galaxy-fold":      ("min-width": 280px,  "max-width": 653px,  "pixel-ratio": 3.0),
 
     // Google Pixel
     // ------------------------------------------------------------------------
-    "google-pixel":     ("min-width":  411px, "max-width":  731px, "pixel-ratio": 2.6),
-    "google-pixel-5":   ("min-width":  393px, "max-width":  851px, "pixel-ratio": 3),
+    
+    /// Google Pixel
+    /// Google Pixel devices with varying screen sizes and pixel densities.
+    "google-pixel":     ("min-width": 411px,  "max-width": 731px,  "pixel-ratio": 2.6),
+    "google-pixel-5":   ("min-width": 393px,  "max-width": 851px,  "pixel-ratio": 3.0),
 
-    // Microsoft Surface
+    
+    /// Other Smartphones
+    /// Other popular smartphones with varying screen sizes and pixel densities.
+    "lg-g6":            ("min-width": 360px,  "max-width": 720px,  "pixel-ratio": 4.0),
+    "oneplus-7t":       ("min-width": 412px,  "max-width": 732px,  "pixel-ratio": 2.5),
+    "sony-xperia-1":    ("min-width": 384px,  "max-width": 643px,  "pixel-ratio": 3.0),
+    "huawei-p30":       ("min-width": 360px,  "max-width": 780px,  "pixel-ratio": 3.0),
+    "xiaomi-mi9":       ("min-width": 393px,  "max-width": 851px,  "pixel-ratio": 3.0),
+ 
+    // Tablets
+    // ========================================================================
+
+    // iPads
     // ------------------------------------------------------------------------
-    "surface-duo":      ("min-width":  540px, "max-width":  720px, "pixel-ratio": 2.5),
-    "surface-pro":      ("min-width":  768px, "max-width": 1366px, "pixel-ratio": 2),
 
-    // Samsung Galaxy Fold
+    
+    /// iPads
+    /// Various models of Apple's iPad, including iPad, iPad Pro, iPad Mini, and iPad Air.
+    "ipad":             ("min-width": 768px,  "max-width": 1024px, "pixel-ratio": 2.0),
+    "ipad-pro":         ("min-width": 1024px, "max-width": 1366px, "pixel-ratio": 2.0),
+    "ipad-mini":        ("min-width": 768px,  "max-width": 1024px, "pixel-ratio": 2.0),
+    "ipad-air":         ("min-width": 820px,  "max-width": 1180px, "pixel-ratio": 2.0),
+
+    // Microsoft Surface
     // ------------------------------------------------------------------------
-    "galaxy-fold":      ("min-width":  280px, "max-width":  653px, "pixel-ratio": 3),
+    
+    /// Microsoft Surface
+    /// Microsoft's Surface devices, including Surface Duo and Surface Pro.
+    "surface-duo":      ("min-width": 540px,  "max-width": 720px,  "pixel-ratio": 2.5),
+    "surface-pro":      ("min-width": 768px,  "max-width": 1366px, "pixel-ratio": 2.0),
+
+    // Desktops & Laptops
+    // ========================================================================
 
-    // Other Tablets and Laptops
+    // Desktops & Larger Tablets
     // ------------------------------------------------------------------------
-    "amazon-fire-hd":    ("min-width":  800px, "max-width": 1280px, "pixel-ratio": 1.5),
+    
+    /// Desktops & Larger Tablets
+    /// Larger devices like desktops and large tablets.
+    "amazon-fire-hd":   ("min-width": 800px,  "max-width": 1280px, "pixel-ratio": 1.5),
     "microsoft-laptop": ("min-width": 1504px, "max-width": 2256px, "pixel-ratio": 1.5),
-
-    // Desktops
+    
+    // Mac Devices
     // ------------------------------------------------------------------------
-    "macbook-air":      ("min-width": 1440px, "max-width": 2560px, "pixel-ratio": 2),
-    "macbook-pro":      ("min-width": 1680px, "max-width": 3072px, "pixel-ratio": 2),
-    "imac":             ("min-width": 1920px, "max-width": 5120px, "pixel-ratio": 2),
+    
+    /// Mac Devices
+    /// Various Apple Mac devices, including MacBook Air, MacBook Pro, and iMac.
+    "macbook-air":      ("min-width": 1440px, "max-width": 2560px, "pixel-ratio": 2.0),
+    "macbook-pro":      ("min-width": 1680px, "max-width": 3072px, "pixel-ratio": 2.0),
+    "imac":             ("min-width": 1920px, "max-width": 5120px, "pixel-ratio": 2.0),
 
     // Additional Devices
     // ------------------------------------------------------------------------
-    "lg-g6":            ("min-width":  360px, "max-width":  720px, "pixel-ratio": 4),
-    "oneplus-7t":       ("min-width":  412px, "max-width":  732px, "pixel-ratio": 2.5),
-    "sony-xperia-1":    ("min-width":  384px, "max-width":  643px, "pixel-ratio": 3),
-    "huawei-p30":       ("min-width":  360px, "max-width":  780px, "pixel-ratio": 3),
-    "xiaomi-mi9":       ("min-width":  393px, "max-width":  851px, "pixel-ratio": 3),
-    "surface-book":     ("min-width": 1500px, "max-width": 2000px, "pixel-ratio": 2),
-    "dell-xps":         ("min-width": 1920px, "max-width": 3840px, "pixel-ratio": 2),
-    "lenovo-thinkpad":  ("min-width": 1440px, "max-width": 2560px, "pixel-ratio": 2),
-
-);
+    
+    /// Other Laptops
+    /// Other popular laptops, including Surface Book, Dell XPS, and Lenovo ThinkPad.
+    "surface-book":     ("min-width": 1500px, "max-width": 2000px, "pixel-ratio": 2.0),
+    "dell-xps":         ("min-width": 1920px, "max-width": 3840px, "pixel-ratio": 2.0),
+    "lenovo-thinkpad":  ("min-width": 1440px, "max-width": 2560px, "pixel-ratio": 2.0)
+
+);

package/scss/variables/_index.scss

@@ -1,31 +1,99 @@
-// 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
+////
+/// 
+/// Variables Module
+/// ===========================================================================
+/// 
+/// This module consolidates and forwards SCSS partials that define variables
+/// for consistent use throughout the project. Each forwarded file encapsulates
+/// a specific category of variables, ensuring modularity, clarity, and ease of
+/// maintenance.
+/// 
+/// Forwarded Modules Overview:
+/// - `layer`: Variables related to layout layers and z-indexing.
+/// - `paper`: Defines color palettes, textures, and backgrounds.
+/// - `unit`: Measurement units, spacing, and size-related variables.
+/// - `scale`: Scaling factors for typography and responsive elements.
+/// - `view`: Variables tied to viewport-specific breakpoints.
+/// - `device`: Device-specific configurations to enhance responsive design.
+/// - `color`: Centralized color definitions for consistent theming.
+/// - `ratio`: Aspect ratio configurations for responsive elements.
+/// 
+/// @group Variables
+/// @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.gl | Variables
+// Forward
 // ============================================================================
 
-@forward "layer";
+
+/// 
+/// Forwards variables related to layout layers and z-indexing, ensuring
+/// consistent layering and stacking order throughout the project.
+/// 
+@forward "layer";  // Layout layers and z-index variables
+
+
+/// 
+/// Forwards variables defining paper sizes etc.
+/// 
 @forward "paper";
 
 
+/// 
+/// Forwards variables managing scaling factors for typography and responsive
+/// elements, ensuring that elements scale proportionally across different
+/// viewports.
+/// 
+@forward "scale";  // Typography scaling and responsive element sizing
+
+
+/// 
+/// Forwards viewport-specific variables, such as breakpoints, to facilitate
+/// responsive design practices.
+/// 
+@forward "view";  // Viewport-specific variables and breakpoints
+
+
+/// 
+/// Forwards device-specific configurations that aid in creating responsive
+/// designs tailored to various devices.
+/// 
+@forward "device";  // Device-specific responsive design variables
+
+
+/// 
+/// Forwards centralized color definitions, providing a consistent color scheme
+/// across the project.
+/// 
+@forward "color";  // Centralized color definitions for the project
 
-@forward "unit";
 
-@forward "scale";
+/// 
+/// Forwards aspect ratio configurations that ensure responsive elements
+/// maintain their intended proportions across different devices and viewports.
+/// 
+@forward "ratio";  // Aspect ratio configurations for responsive elements
 
-@forward "view";
+/// 
+/// Forwards variables related to measurement units, spacing, and size
+/// definitions. Useful for maintaining consistent sizing across different
+/// components.
+/// 
+@forward "unit";  // Measurement units and spacing
 
-@forward "device";

package/scss/variables/_layer.scss

@@ -1,58 +1,155 @@
-// 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.
-
-
-
-/// Layer Map
-/// Z-index Layers
+// ============================================================================
+// Poster
+// ============================================================================
+
+////
+/// 
+/// Layer Variables Module
+/// ===========================================================================
+/// 
+/// @group Layer
+/// @author Scape Agency
+/// @link https://unit.gl
+/// @since 0.1.0 initial release
+/// @todo None
+/// @access public
+/// 
+////
+
+
+// ============================================================================
+// Use
+// ============================================================================
+
+
+// ============================================================================
+// Variables
+// ============================================================================
+
+
+/// 
+/// Z-Index Layer Map
+/// ---------------------------------------------------------------------------
+///
+/// A map defining the z-index layers used to manage the stacking order of UI
+/// elements. Each key in the map represents a specific layer, with an
+/// associated numeric value indicating its z-index.
+/// 
+/// This map defines the z-index layers used throughout the project to manage
+/// the stacking order of various interface elements. Adjustments can be made
+/// by modifying the values associated with each layer.
+/// 
+/// - **Guides**: High-priority overlays for design guides.
+/// - **Overlays**: Elements like modals that need to appear above other content.
+/// - **Interface Elements**: General UI components, ribbons, and controls.
+/// - **Content**: Main content areas, typically stacked below UI elements.
+/// - **Background Layers**: Base layers like canvases, typically behind content.
+/// - **Special Values**: Special z-index values for maximum, minimum, and baseline.
+/// 
+/// @name layers
+/// @type Map
+/// 
+/// @example scss - Usage Example
+///   .element {
+///     z-index: z('modal');
+///   }
+/// 
+/// @todo Add more layers as needed, ensuring consistent and clear naming.
+///
 $layers: (
 
+    // ========================================================================
     // Guides
-    "guides":              9998,
-    "guide_baseline":      3000,
-    "guide_graph":         3100,
-
+    // ========================================================================
+    
+    /// High-priority guide overlays for design and debugging.
+    /// @name guides
+    /// @type Number
+    "guides":              9998,  // High priority guide overlays
+
+ 
+    /// Baseline guide used for text alignment and visual rhythm.
+    /// @name guide_baseline
+    /// @type Number
+    "guide_baseline":      3000,  // Baseline guide for text alignment
+
+ 
+    /// Graphical guides, such as grid overlays, used in design.
+    /// @name guide_graph
+    /// @type Number
+    "guide_graph":         3100,  // Graphical guides, such as grids
+
+    // ========================================================================
     // Overlays
-    "modal":               7000,
-
-    // Interface
-    "ribbon":               5000,
-    "interface":            4000,
-    "control":              3000,
-
+    // ========================================================================
+
+ 
+    /// Z-index for modals and dialog boxes, ensuring they appear above other content.
+    /// @name modal
+    /// @type Number
+    "modal":               7000,  // Modals and dialog boxes
+
+    // ========================================================================
+    // Interface Elements
+    // ========================================================================
+
+ 
+    /// Z-index for top ribbons and banners that overlay other UI elements.
+    /// @name ribbon
+    /// @type Number
+    "ribbon":              5000,  // Top ribbons, banners
+
+ 
+    /// General interface elements like headers, footers, and sidebars.
+    /// @name interface
+    /// @type Number
+    "interface":           4000,  // General interface elements
+
+ 
+    /// Controls like buttons, sliders, and other interactive elements.
+    /// @name control
+    /// @type Number
+    "control":             3000,  // Controls like buttons, sliders
+
+    // ========================================================================
     // Content
-    "content":              2000,
-
-    // Canvas
-    "canvas":              -1000,
-    // "canvas":              5000,
-
-  // 
-  "max": 9999,
-  "mid": 0,
-  "min": -9999,
-
-  // Add more layers as needed
+    // ========================================================================
+
+    
+    /// Main content area, typically stacked below UI elements.
+    /// @name content
+    /// @type Number
+    "content":             2000,  // Main content area
+
+    // ========================================================================
+    // Background Layers
+    // ========================================================================
+
+    
+    /// Background canvas or base layer, typically the lowest layer.
+    /// @name canvas
+    /// @type Number
+    "canvas":             -1000,  // Background canvas or base layer
+
+    // ========================================================================
+    // Special Values
+    // ========================================================================
+    
+    /// Maximum possible z-index value.
+    /// @name max
+    /// @type Number
+    "max": 9999,  // Maximum possible z-index
+
+    
+    /// Default, baseline z-index value.
+    /// @name mid
+    /// @type Number
+    "mid": 0,  // Default, baseline z-index
+
+    
+    /// Minimum possible z-index value.
+    /// @name min
+    /// @type Number
+    "min":m-9999,  // Minimum possible z-index
 
 ) !default;
-
-
-/// Layer Function
-/// Retrieve z-index from the layers map
-@function z($layer) {
-    @if not map-has-key($layers, $layer) {
-        @warn "No layer found for `#{$layer}` in $z-layers map. Property omitted.";
-    }
-    @return map-get($layers, $layer);
-}