unit.gl 0.0.35 → 0.0.39

package/scss/variables/_scale.scss

@@ -1,146 +1,272 @@
-// 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
+////
+/// 
+/// Scale Variables Module
+/// ===========================================================================
+/// 
+/// This module defines the base typographic and spacing scales used throughout
+/// the project, leveraging a rhythm-based approach for consistent vertical 
+/// spacing and typographic hierarchy. The Kyū Point and Baseline scales 
+/// provide a flexible system for responsive design.
+/// 
+/// @group Scale
+/// @author Scape Agency
+/// @link https://unit.gl
+/// @since 0.1.0 initial release
+/// @todo None
+/// @requires "unit" - module for unit conversion and scaling functions.
+/// @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 "unit" as *;
 
 
-// $rhythm_base: q(4);
-$rhythm_base: $q *4;
+// ============================================================================
+// Variables
+// ============================================================================
 
-$line_height_ratio: 1.5;
 
-$font_size_scalar:  4;
-$line_height_scalar:  calc($line_height_ratio * $font_size_scalar);
+/// 
+/// The base rhythm unit used for vertical spacing and typography.
+/// 
+/// @name $rhythm_base
+/// @type Length
+/// 
+$rhythm_base: $q * 4 !default;
 
 
+/// 
+/// The ratio of line height to font size, defining the line height.
+/// 
+/// @name $line_height_ratio
+/// @type Number
+/// 
+$line_height_ratio: 1.5 !default;
 
-$font_size_base:    calc($font_size_scalar * $rhythm_base); // Base font size
-$line_height_base:  calc($line_height_scalar * $rhythm_base); // Base line height (1.5 times the font size is a good start)
 
+/// 
+/// A scalar to define the base font size relative to the rhythm base.
+/// 
+/// @name $font_size_scalar
+/// @type Number
+/// 
+$font_size_scalar: 4 !default;
 
 
-// Typography ladder map
-$typographic_scale: (
-    1:  q( 4),
-    2:  q( 6), // +2
-    3:  q( 8), // +2
-    4:  q(10), // +2
-    5:  q(12), // +2
-    6:  q(14), // +2
-    7:  q(16), // +2
-    8:  q(20), // +4
-    9:  q(24), // +4
-    10: q(28), // +4
-    11: q(32), // +4
-    12: q(36), // +4
-    13: q(40), // +4
-    14: q(48), // +8
-    15: q(56), // +8
-    16: q(64), // +8
-    17: q(72), // +8
-) !default;
+/// 
+/// A scalar to define the base line height, calculated from the line height
+/// ratio and font size scalar.
+/// 
+/// @name $line_height_scalar
+/// @type Length
+/// 
+$line_height_scalar: calc($line_height_ratio * $font_size_scalar) !default;
+
 
-//     'display': $q-base * 96,  // For large display text
-//     'h1': $q-base * 48,       // For primary headings
-//     'h2': $q-base * 36,       // For secondary headings
-//     'h3': $q-base * 24,       // For tertiary headings
-//     'h4': $q-base * 20,       // For quaternary headings
-//     'h5': $q-base * 18,       // For quinary headings
-//     'h6': $q-base * 16,       // For senary headings
-//     'body-large': $q-base * 14, // For large body text
-//     'body': $q-base * 12,     // For main body text
-//     'body-small': $q-base * 10, // For small body text
-//     'caption': $q-base * 8,   // For captions and overlines
-//     'overline': $q-base * 6   // For the smallest size, like legal text
-// ) !default;
+/// 
+/// The base font size, calculated as a multiple of the rhythm base.
+/// 
+/// @name $font_size_base
+/// @type Length
+/// 
+$font_size_base: calc($font_size_scalar * $rhythm_base) !default;
 
 
+/// 
+/// The base line height, calculated from the line height scalar and rhythm
+/// base.
+/// 
+/// @name $line_height_base
+/// @type Length
+/// 
+$line_height_base: calc($line_height_scalar * $rhythm_base) !default;
+
+
+/// 
+/// Typographic Scale Map
+/// ---------------------------------------------------------------------------
+/// 
+/// A modular scale for typography, based on rhythm units. Each step in the
+/// scale is a multiple of the rhythm base.
+/// 
+/// @name $typographic_scale
+/// @type Map
+/// 
+$typographic_scale: (
+     1: q(4),
+     2: q(6),  // +2 units
+     3: q(8),  // +2 units
+     4: q(10), // +2 units
+     5: q(12), // +2 units
+     6: q(14), // +2 units
+     7: q(16), // +2 units
+     8: q(20), // +4 units
+     9: q(24), // +4 units
+    10: q(28), // +4 units
+    11: q(32), // +4 units
+    12: q(36), // +4 units
+    13: q(40), // +4 units
+    14: q(48), // +8 units
+    15: q(56), // +8 units
+    16: q(64), // +8 units
+    17: q(72)  // +8 units
+) !default;
 
-// Kyu Point Scale
-// ----------------------------------------------------------------------------
 
-$basepoint_scale: 4;
+///
+///  Kyū Point Scale
+/// ---------------------------------------------------------------------------
+/// 
+/// The base scaling factor for the Kyū point scale.
+/// 
+/// @name $basepoint_scale
+/// @type Number
+/// 
+$basepoint_scale: 4 !default;
 
+
+/// 
+/// Calculates a Kyū point value based on the basepoint scale.
+/// 
+/// @name basepoint
+/// @param {Number} $value - The multiplier to apply to the base point scale.
+/// @return {Length} The calculated Kyū point value.
+/// 
 @function basepoint($value) {
     @return calc($q * $value * $basepoint_scale);
 }
 
-$basepoint_01: basepoint( 1) !default;
-$basepoint_02: basepoint( 2) !default;
-$basepoint_03: basepoint( 3) !default;
-$basepoint_04: basepoint( 4) !default;
-$basepoint_05: basepoint( 5) !default;
-$basepoint_06: basepoint( 6) !default;
-$basepoint_07: basepoint( 7) !default;
-$basepoint_08: basepoint( 8) !default;
-$basepoint_09: basepoint( 9) !default;
-$basepoint_10: basepoint(10) !default;
-$basepoint_11: basepoint(11) !default;
-$basepoint_12: basepoint(12) !default;
 
+/// 
+/// A scale of Kyū points, used for fine-tuned spacing and sizing.
+/// 
+/// @name $basepoint
+/// @type Map
+/// 
 $basepoint: (
-    1:  basepoint( 1),
-    2:  basepoint( 2),
-    3:  basepoint( 3),
-    4:  basepoint( 4),
-    5:  basepoint( 5),
-    6:  basepoint( 6),
-    7:  basepoint( 7),
-    8:  basepoint( 8),
-    9:  basepoint( 9),
+    1: basepoint(1),
+    2: basepoint(2),
+    3: basepoint(3),
+    4: basepoint(4),
+    5: basepoint(5),
+    6: basepoint(6),
+    7: basepoint(7),
+    8: basepoint(8),
+    9: basepoint(9),
     10: basepoint(10),
     11: basepoint(11),
-    12: basepoint(12),
+    12: basepoint(12)
 ) !default;
 
 
-// Kyu Baseline Scale
-// ----------------------------------------------------------------------------
+///
+/// Kyū Baseline Scale
+/// ---------------------------------------------------------------------------
+/// 
+/// The base scaling factor for the Kyū baseline grid.
+/// 
+/// @name $baseline_scale
+/// @type Number
+/// 
+$baseline_scale: 5 !default;
 
-$baseline_scale: 5;
 
+/// 
+/// Calculates a baseline grid value based on the baseline scale.
+/// 
+/// @name baseline
+/// @type Function
+/// @param {Number} $value - The multiplier to apply to the baseline scale.
+/// @return {Length} The calculated baseline grid value.
+/// 
 @function baseline($value) {
-  @return calc($q * $value * $baseline_scale);
+    @return calc($q * $value * $baseline_scale);
 }
 
-$baseline_00: baseline( 1) !default;
-$baseline_01: baseline( 1) !default;
-$baseline_02: baseline( 2) !default;
-$baseline_03: baseline( 3) !default;
-$baseline_04: baseline( 4) !default;
-$baseline_05: baseline( 5) !default;
-$baseline_06: baseline( 6) !default;
-$baseline_07: baseline( 7) !default;
-$baseline_08: baseline( 8) !default;
-$baseline_09: baseline( 9) !default;
-$baseline_10: baseline(10) !default;
-$baseline_11: baseline(11) !default;
-$baseline_12: baseline(12) !default;
-
+/// 
+/// A scale for the baseline grid, used for consistent vertical rhythm in
+/// layouts.
+/// 
+/// @name $baseline
+/// @type Map
+/// 
 $baseline: (
-    1:  baseline( 1),
-    2:  baseline( 2),
-    3:  baseline( 3),
-    4:  baseline( 4),
-    5:  baseline( 5),
-    6:  baseline( 6),
-    7:  baseline( 7),
-    8:  baseline( 8),
-    9:  baseline( 9),
+    1: baseline(1),
+    2: baseline(2),
+    3: baseline(3),
+    4: baseline(4),
+    5: baseline(5),
+    6: baseline(6),
+    7: baseline(7),
+    8: baseline(8),
+    9: baseline(9),
     10: baseline(10),
     11: baseline(11),
-    12: baseline(12),
+    12: baseline(12)
 ) !default;
 
+
+/// 
+/// Musical Scales Map
+/// ---------------------------------------------------------------------------
+/// 
+/// A map representing various musical scales by their degree.
+/// These scales can be used to inform design decisions, such as rhythm-based
+/// spacing or modular scale ratios in typography.
+/// 
+/// @name scale_musical
+/// @type Map
+/// 
+$scale_musical: (
+    "monotonic":    1,   // Single tone scale
+    "ditonic":      2,   // Two-tone scale
+    "tritonic":     3,   // Three-tone scale
+    "tetratonic":   4,   // Four-tone scale
+    "pentatonic":   5,   // Five-tone scale, commonly used in music
+    "hexatonic":    6,   // Six-tone scale
+    "peptatonic":   7,   // Seven-tone scale
+    "octatonic":    8,   // Eight-tone scale
+    "nonatonic":    9,   // Nine-tone scale
+    "dodecatonic": 12    // Twelve-tone scale, covers all semitones in an octave
+) !default;
+
+
+/// Classic Typographic Scale
+/// ---------------------------------------------------------------------------
+/// 
+/// A classic typographic scale that has historical significance,
+/// often used in design software and by typographers since the Renaissance.
+/// This scale ensures harmonious and aesthetically pleasing text sizing.
+/// 
+/// @name typographic_scale_classic
+/// @type Map
+/// 
+$typographic_scale_classic: (
+    1:  q( 6),  // 6q
+    2:  q( 7),  // 7q  (+1)
+    3:  q( 8),  // 8q  (+1)
+    4:  q( 9),  // 9q  (+1)
+    5:  q(10),  // 10q (+1)
+    6:  q(11),  // 11q (+1)
+    7:  q(12),  // 12q (+1)
+    8:  q(14),  // 14q (+2)
+    9:  q(16),  // 16q (+2)
+    10: q(18),  // 18q (+2)
+    11: q(21),  // 21q (+3)
+    12: q(24),  // 24q (+3)
+    13: q(36),  // 36q (+12)
+    14: q(48),  // 48q (+12)
+    15: q(60),  // 60q (+12)
+    16: q(72),  // 72q (+12)
+    17: q(84),  // 84q (+12)
+    18: q(96)   // 96q (+12)
+) !default;

package/scss/variables/_unit.scss

@@ -1,21 +1,33 @@
-// 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
+// ============================================================================
 
+////
+/// 
+/// Unit Variables Module
+/// ===========================================================================
+/// 
+/// This module defines a responsive typography system using the Kyū
+/// measurement system. The system is based on the rem unit and provides
+/// utility functions and mixins to apply fluid typography across various
+/// screen sizes.
+/// 
+/// Dependencies:
+/// - view: For viewport-related variables.
+/// - functions: For utility functions such as `unit_strip`.
+///
+/// @group Unit
+/// @author Scape Agency
+/// @link https://unit.gl
+/// @since 0.1.0 initial release
+/// @todo None
+/// @access public
+/// 
+////
 
 
 // ============================================================================
-// Base | Unit
+// Use
 // ============================================================================
 
 @use "sass:math";
@@ -23,81 +35,73 @@
 @use "../functions" as *;
 
 
-// Kyū Measurement System for Responsive Typography
-// Defines a base size and provides a mixin for fluid typography.
+// ============================================================================
+// Variables
+// ============================================================================
 
 
-// Kyū base size definition (A Kyū is 1/16th of a Rem).
-// 1rem equals the font size of the html element, which for most browsers has
-// a default value of 16px.
+///
+/// The base unit in the Kyū measurement system. It represents 1/16th of a rem,
+/// which is equivalent to 1px or 0.25mm.
+/// 
+/// @name $q
+/// @type Length
+/// 
 $q: 0.0625rem !default;  // 1px, or 0.25mm
 
 
-// Function to calculate multiples of 'q'
-@function q($multiplier) {
-    @return calc($q * $multiplier);
-}
+/// 
+/// The minimum Kyū size used for fluid typography.
+/// 
+/// @type Length
+/// @name $q_min
+/// 
+$q_min: 0.75px !default;
 
-// Mixin to apply multiples of 'q'
-@mixin q($multiplier, $property) {
-    #{$property}: q($multiplier);
-}
 
+/// 
+/// The maximum Kyū size used for fluid typography.
+/// 
+/// @type Length
+/// @name $q_max
+$q_max: 1.50px !default;
 
-// Root custom properties for Kyū sizes
-:root {
-    --q: $q;
-}
 
+/// 
+/// The minimum font size calculated using the minimum Kyū size, based on
+/// the rem unit.
+/// 
+/// @type Length
+/// @name $font_min
+/// 
+$font_min: calc((1rem / $q) * $q_min) !default;
 
-// Minimum and maximum Kyū sizes
-$q_min: 0.75px !default;
-$q_max: 1.50px !default;
 
-// Minimum and maximum Kyū sizes
-$font_min: calc((1rem / $q) * $q_min) !default;
+///
+/// The maximum font size calculated using the maximum Kyū size, based on
+/// the rem unit.
+/// 
+/// @type Length
+/// @name $font_max
 $font_max: calc((1rem / $q) * $q_max) !default;
 
-// @mixin fluid_type($min-vw, $max-vw, $min-font-size, $max-font-size) {
-//     // Assign font-size for the starting viewport width
-//     font-size: $min-font-size;
-
-//     // Apply fluid scaling between the minimum and maximum viewport widths
-//     @media screen and (min-width: $min-vw) {
-//         font-size: calc(#{$min-font-size} + #{unitless($max-font-size - $min-font-size)} * ((100vw - #{$min-vw}) / #{unitless($max-vw - $min-vw)}));
-//     }
-
-//     // Fix the font-size at the maximum size beyond the maximum viewport width
-//     @media screen and (min-width: $max-vw) {
-//         font-size: $max-font-size;
-//     }
-// }
-
-@mixin fluid_type($min-vw, $max-vw, $min-font-size, $max-font-size) {
-    $u1: unit($min-vw);
-    $u2: unit($max-vw);
-    $u3: unit($min-font-size);
-    $u4: unit($max-font-size);
-
-    @if $u1 == $u2 and $u1 == $u3 and $u1 == $u4 {
-        & {
-            font-size: $min-font-size;
-            @media screen and (min-width: $min-vw) {
-                font-size: calc(#{$min-font-size} + #{unit_strip($max-font-size - $min-font-size)} * ((100vw - #{$min-vw}) / #{unit_strip($max-vw - $min-vw)}));
-            }
-            @media screen and (min-width: $max-vw) {
-                font-size: $max-font-size;
-            }
-        }
-    }
-}
 
 
 
-html {
-    @include fluid_type($media_xs, $media_sl, $font_min, $font_max);
-}
 
 
 
 
+
+
+/// 
+/// This function returns a calculated value in Kyū units, making it easy to
+/// apply multiples of the base unit.
+/// 
+/// @name q
+/// @param {Number} $multiplier - The multiplier to apply to the base Kyū unit.
+/// @return {Length} The calculated value in Kyū units.
+/// 
+@function q($multiplier) {
+    @return calc($q * $multiplier);
+}