unit.gl 0.0.35 → 0.0.39

package/scss/functions/_sequence.scss

@@ -1,96 +1,100 @@
-// 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
+////
+/// 
+/// Sequence Functions Module
+/// ===========================================================================
+/// 
+/// This module provides various functions to calculate terms in well-known 
+/// mathematical sequences such as Fibonacci, Lucas, Prime numbers, and more. 
+/// Each function is designed to compute the nth term in the respective 
+/// sequence using a straightforward algorithm.
+/// 
+/// @group Sequence
+/// @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
+// ============================================================================
 
 
 // ============================================================================
-// Math | Number Sequences
+// Functions
 // ============================================================================
 
 
-// Fibonacci Number Sequence
-// ----------------------------------------------------------------------------
-
+///
+/// Fibonacci Number Sequence
+/// ---------------------------------------------------------------------------
+/// 
 /// Calculates the nth Fibonacci number using a recursive approach.
-/// In mathematics, the Fibonacci numbers form a sequence such that each number
-/// is the sum of the two preceding ones, usually starting with 0 and 1.
+/// Fibonacci numbers form a sequence where each number is the sum of the two 
+/// preceding ones, starting with 0 and 1.
+/// 
+/// @name sequence_fibonacci
 /// @param {Number} $n - The position in the Fibonacci sequence to calculate.
 /// @return {Number} - The nth Fibonacci number.
-@function sequence_fibonacci($n) {
-
-    // Return null for negative index to avoid unnecessary recursion
+/// 
+ @function sequence_fibonacci($n) {
     @if $n < 0 {
-        @warn "Index #{$n} is not valid for Fibonacci sequence.";
+        @warn "Index #{$n} is not valid for the Fibonacci sequence.";
         @return null;
     }
-
-    // Base cases
-    @if $n == 0 {
-        @return 0;
-    } @else if $n == 1 {
-        @return 1;
-    } @else {
-        // Recursive case
+    @if $n == 0 { @return 0; }
+    @else if $n == 1 { @return 1; }
+    @else {
         @return sequence_fibonacci($n - 1) + sequence_fibonacci($n - 2);
     }
-
 }
 
 
-// Lucas Number Sequence
-// ----------------------------------------------------------------------------
-
+///
+/// Lucas Number Sequence
+/// ---------------------------------------------------------------------------
+///
 /// Calculates the nth Lucas number using a recursive approach.
-/// In mathematics, the Lucas numbers are an integer sequence named after the
-/// mathematician François Édouard Anatole Lucas (1842–1891), who studied both
-/// that sequence and the closely related Fibonacci numbers. Lucas numbers and
-/// Fibonacci numbers form complementary instances of Lucas sequences
+/// Lucas numbers form a sequence similar to Fibonacci numbers but start with 
+/// 2 and 1 instead of 0 and 1.
+/// 
+/// @name sequence_lucas
 /// @param {Number} $n - The position in the Lucas sequence to calculate.
 /// @return {Number} - The nth Lucas number.
+/// 
 @function sequence_lucas($n) {
-
-    // Return null for negative index to avoid unnecessary recursion
     @if $n < 0 {
-        @warn "Index #{$n} is not valid for Lucas sequence.";
+        @warn "Index #{$n} is not valid for the Lucas sequence.";
         @return null;
     }
-
-    // Base cases
-    @if $n == 0 {
-        @return 2;
-    } @else if $n == 1 {
-        @return 1;
-    } @else {
-        // Recursive case
+    @if $n == 0 { @return 2; }
+    @else if $n == 1 { @return 1; }
+    @else {
         @return sequence_lucas($n - 1) + sequence_lucas($n - 2);
     }
-
 }
 
 
-// Prime Number Sequence
-// ----------------------------------------------------------------------------
-
-/// Checks if a number is a prime number.
-/// Prime numbers are natural numbers greater than 1 that are not a product
-/// of two smaller natural numbers.
-/// This function returns true if the number is prime, otherwise false.
+///
+/// Prime Number Check
+/// ---------------------------------------------------------------------------
+/// 
+/// Checks if a number is prime.
+/// A prime number is a natural number greater than 1 that has no positive 
+/// divisors other than 1 and itself.
+/// @name is_prime
 /// @param {Number} $n - The number to check.
 /// @return {Boolean} - `true` if the number is prime, `false` otherwise.
+/// 
 @function is_prime($n) {
-    @if $n <= 1 {
-        @return false;
-    }
+    @if $n <= 1 { @return false; }
     @for $i from 2 through math.sqrt($n) {
         @if $n % $i == 0 {
             @return false;
@@ -100,12 +104,17 @@
 }
 
 
-// Catalan Number Sequence
-// ----------------------------------------------------------------------------
-
+///
+/// Factorial
+/// ---------------------------------------------------------------------------
+/// 
 /// Calculates the factorial of a number.
-/// @param {Number} $n - The number to calculate factorial for.
+/// Factorial is the product of all positive integers up to a given number.
+/// 
+/// @name factorial
+/// @param {Number} $n - The number to calculate the factorial for.
 /// @return {Number} - The factorial of $n.
+/// 
 @function factorial($n) {
     $result: 1;
     @for $i from 1 through $n {
@@ -114,59 +123,75 @@
     @return $result;
 }
 
+///
+/// Catalan Number Sequence
+/// ---------------------------------------------------------------------------
+/// 
 /// Calculates the nth Catalan number.
-/// Catalan numbers are a sequence of natural numbers that have found
-/// applications in various combinatorial problems. The nth Catalan number
-/// is calculated using the formula C(n) = (2n)! / (n+1)!n!.
-/// @param {Number} $n - The position in the Catalan series to calculate.
+/// Catalan numbers are a sequence of natural numbers with applications in 
+/// combinatorial mathematics, such as counting certain types of lattice paths.
+/// 
+/// @name sequence_catalan
+/// @param {Number} $n - The position in the Catalan sequence to calculate.
 /// @return {Number} - The nth Catalan number.
+/// 
 @function sequence_catalan($n) {
     @return factorial(2 * $n) / (factorial($n + 1) * factorial($n));
 }
 
 
-// Harmonic Sequence
-// ----------------------------------------------------------------------------
-
+///
+/// Harmonic Sequence
+/// ---------------------------------------------------------------------------
+/// 
 /// Calculates the nth term of the harmonic series.
-/// The harmonic series is the sum of reciprocals of the positive integers.
-/// For simplicity, we calculate the nth term as 1/n.
+/// The harmonic series is the sum of the reciprocals of the positive integers.
+/// 
+/// @name sequence_harmonic
 /// @param {Number} $n - The position in the harmonic series to calculate.
 /// @return {Number} - The nth term of the harmonic series.
+/// 
 @function sequence_harmonic($n) {
     @if $n <= 0 {
-        @warn "Index #{$n} is not valid for harmonic series.";
+        @warn "Index #{$n} is not valid for the harmonic series.";
         @return null;
     }
     @return 1 / $n;
 }
 
 
-// Geometric Sequence
-// ----------------------------------------------------------------------------
-
+///
+/// Geometric Sequence
+/// ----------------------------------------------------------------------------
+/// 
 /// Calculates the nth term of a geometric series with a ratio of 2.
-/// The geometric series is a series with a constant ratio between successive
-/// terms. Here we calculate the nth term for a series with a ratio of 2 
-/// (doubling each term).
+/// A geometric series has a constant ratio between successive terms. 
+/// This function calculates the nth term for a series where each term doubles.
+/// 
+/// @name sequence_geometric
 /// @param {Number} $n - The position in the geometric series to calculate.
 /// @return {Number} - The nth term of the geometric series.
+/// 
 @function sequence_geometric($n) {
     @if $n < 0 {
-        @warn "Negative index #{$n} is not valid for geometric series.";
+        @warn "Negative index #{$n} is not valid for the geometric series.";
         @return null;
     }
     @return pow(2, $n - 1);
 }
 
 
-// Superfactorial Sequence
-// ----------------------------------------------------------------------------
-
+///
+/// Superfactorial Sequence
+/// ---------------------------------------------------------------------------
+/// 
 /// Calculates the superfactorial of a number.
 /// The superfactorial of a number n is the product of the first n factorials.
-/// @param {Number} $n - The number to calculate superfactorial for.
+/// 
+/// @name sequence_superfactorial
+/// @param {Number} $n - The number to calculate the superfactorial for.
 /// @return {Number} - The superfactorial of $n.
+/// 
 @function sequence_superfactorial($n) {
     $result: 1;
     @for $i from 1 through $n {
@@ -180,98 +205,101 @@
 }
 
 
-// Triangular Number Sequence
-// ----------------------------------------------------------------------------
-
+///
+/// Triangular Number Sequence
+/// ---------------------------------------------------------------------------
+/// 
 /// Calculates the nth triangular number.
-/// In mathematics, a triangular number or triangle number counts objects arranged
-/// in an equilateral triangle. The nth triangular number is the number of dots
-/// Triangular numbers are the sum of the first n natural numbers. The nth
-/// triangular number is n(n + 1)/2.
-/// composing a triangle with n dots on a side.
+/// Triangular numbers are the sum of the first n natural numbers.
+/// 
+/// @name sequence_triangular
 /// @param {Number} $n - The position in the triangular series to calculate.
 /// @return {Number} - The nth triangular number.
+/// 
 @function sequence_triangular($n) {
-
-    // Return null for non-positive index to avoid invalid numbers
     @if $n <= 0 {
-        @warn "Index #{$n} is not valid for triangular series.";
+        @warn "Index #{$n} is not valid for the triangular series.";
         @return null;
     }
-
-    // Calculate the nth triangular number
     @return $n * ($n + 1) / 2;
-
 }
 
 
-// Square Number Sequence
-// ----------------------------------------------------------------------------
-
+///
+/// Square Number Sequence
+/// ---------------------------------------------------------------------------
+/// 
 /// Calculates the nth square number.
-/// Square numbers are numbers that can be expressed as the product of an
-/// integer with itself. The nth square number is n².
+/// Square numbers are numbers that can be expressed as the product of an 
+/// integer with itself (n²).
+/// 
+/// @name sequence_square
 /// @param {Number} $n - The position in the square series to calculate.
 /// @return {Number} - The nth square number.
+/// 
 @function sequence_square($n) {
     @if $n < 0 {
-        @warn "Negative index #{$n} is not valid for square series.";
+        @warn "Negative index #{$n} is not valid for the square series.";
         @return null;
     }
     @return $n * $n;
 }
 
 
-// Pentagonal Number Sequence
-// ----------------------------------------------------------------------------
-
+///
+/// Pentagonal Number Sequence
+/// ---------------------------------------------------------------------------
+/// 
 /// Calculates the nth pentagonal number.
-/// In mathematics, a pentagonal number is a figurate number that extends the
-/// concept of triangular and square numbers to the pentagon.
+/// Pentagonal numbers are figurate numbers that represent a pentagon.
+/// 
+/// @name sequence_pentagonal
 /// @param {Number} $n - The position in the pentagonal series to calculate.
 /// @return {Number} - The nth pentagonal number.
+/// 
 @function sequence_pentagonal($n) {
-
-    // Return null for non-positive index to avoid invalid numbers
     @if $n <= 0 {
-        @warn "Index #{$n} is not valid for pentagonal series.";
+        @warn "Index #{$n} is not valid for the pentagonal series.";
         @return null;
     }
-
-    // Calculate the nth pentagonal number
     @return (3 * $n * $n - $n) / 2;
-
 }
 
 
-// Hexagonal Number Sequence
-// ----------------------------------------------------------------------------
-
+///
+/// Hexagonal Number Sequence
+/// ---------------------------------------------------------------------------
+/// 
 /// Calculates the nth hexagonal number.
-/// Hexagonal numbers are figurate numbers that represent a hexagon. The nth
-/// hexagonal number is given by 2n² - n.
+/// Hexagonal numbers are figurate numbers that represent a hexagon.
+/// 
+/// @name sequence_hexagonal
 /// @param {Number} $n - The position in the hexagonal series to calculate.
 /// @return {Number} - The nth hexagonal number.
+/// 
 @function sequence_hexagonal($n) {
     @if $n <= 0 {
-        @warn "Index #{$n} is not valid for hexagonal series.";
+        @warn "Index #{$n} is not valid for the hexagonal series.";
         @return null;
     }
     @return 2 * $n * $n - $n;
 }
 
 
-// Cube Number Sequence
-// ----------------------------------------------------------------------------
-
+///
+/// Cube Number Sequence
+/// ---------------------------------------------------------------------------
+/// 
 /// Calculates the nth cube number.
-/// Cube numbers are the numbers raised to the power of three.
-/// The nth cube number is n³.
+/// Cube numbers are numbers raised to the power of three (n³).
+/// 
+/// @name sequence_cube
 /// @param {Number} $n - The position in the cube series to calculate.
 /// @return {Number} - The nth cube number.
+/// 
 @function sequence_cube($n) {
     @if $n < 0 {
-        @warn "Negative index #{$n} is not valid for cube series.";
+        @warn "Negative index #{$n} is not valid for the cube series.";
         @return null;
     }
     @return $n * $n * $n;

package/scss/functions/_view.scss

@@ -0,0 +1,40 @@
+// ============================================================================
+// Poster
+// ============================================================================
+
+////
+/// 
+/// View Functions Module
+/// ===========================================================================
+/// 
+/// @group View
+/// @author Scape Agency
+/// @link https://unit.gl
+/// @since 0.1.0 initial release
+/// @todo None
+/// @access public
+/// 
+////
+
+
+// ============================================================================
+// Use
+// ============================================================================
+
+
+// ============================================================================
+// Functions
+// ============================================================================
+
+
+/// 
+/// A function to calculate breakpoints based on a multiplier of the base
+/// screen unit.
+/// 
+/// @name calc_breakpoint
+/// @param {Number} $multiplier - The multiplier to apply to the base unit.
+/// @return {Length} The calculated breakpoint value in pixels.
+/// 
+@function calc_breakpoint($base_screen_unit, $multiplier) {
+    @return $base_screen_unit * $multiplier;
+}

package/scss/functions/math/_arithmetic.scss

@@ -0,0 +1,102 @@
+// ============================================================================
+// Poster
+// ============================================================================
+
+////
+/// 
+/// Math Functions Module
+/// ===========================================================================
+/// 
+/// These functions allow for arithmetic operations on values with or without 
+/// units, ensuring compatibility and proper handling of CSS units. When units 
+/// are mismatched, a warning is issued, and the operation returns null.
+///
+/// Functions:
+/// - add: Adds two values, handling units appropriately.
+/// - subtract: Subtracts one value from another, with unit handling.
+/// 
+/// @group Math
+/// @author Scape Agency
+/// @link https://unit.gl
+/// @since 0.1.0 initial release
+/// @todo None
+/// @access public
+/// 
+////
+
+
+// ============================================================================
+// Use
+// ============================================================================
+
+
+// ============================================================================
+// Functions
+// ============================================================================
+
+
+/// 
+/// Adds two values, handling units appropriately.
+/// 
+/// This function performs arithmetic addition on two values, ensuring that
+/// units are properly handled. If both values are unitless, they are added
+/// directly.
+/// If one value has a unit and the other is unitless, the unitless value is 
+/// treated as having the same unit as the other value. If both values have 
+/// units, they must be the same unit; otherwise, a warning is issued and 
+/// `null` is returned.
+/// 
+/// @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 units.
+/// @return {Number} - The sum of the two values, or null if the units are incompatible.
+/// 
+@function add(
+    $value1,
+    $value2
+) {
+    @if unitless($value1) and 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) {
+        @return $value1 + $value2;
+    } @else {
+        @warn "Cannot add values with different units: #{$value1} and #{$value2}";
+        @return null;
+    }
+}
+
+///
+/// Subtracts one value from another, handling units appropriately.
+/// 
+/// This function performs arithmetic subtraction on two values, ensuring that
+/// units are properly handled. If both values are unitless, they are
+/// subtracted directly.
+/// If one value has a unit and the other is unitless, the unitless value is 
+/// treated as having the same unit as the other value. If both values have 
+/// units, they must be the same unit; otherwise, a warning is issued and 
+/// `null` is returned.
+/// 
+/// @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 units.
+/// @return {Number} - The difference between the two values, or null if the units are incompatible.
+/// 
+@function subtract(
+    $value1,
+    $value2
+) {
+    @if unitless($value1) and 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) {
+        @return $value1 - $value2;
+    } @else {
+        @warn "Cannot subtract values with different units: #{$value1} and #{$value2}";
+        @return null;
+    }
+}

package/scss/functions/math/_index.scss

@@ -0,0 +1,30 @@
+// ============================================================================
+// Poster
+// ============================================================================
+
+////
+/// 
+/// Math Functions Module
+/// ===========================================================================
+/// 
+/// @group Math
+/// @author Scape Agency
+/// @link https://unit.gl
+/// @since 0.1.0 initial release
+/// @todo None
+/// @access public
+/// 
+////
+
+
+// ============================================================================
+// Use
+// ============================================================================
+
+
+// ============================================================================
+// Forward
+// ============================================================================
+
+
+@forward "arithmetic";        // Basic arithmetic operations

package/scss/functions/unit/_index.scss

@@ -0,0 +1,30 @@
+// ============================================================================
+// Poster
+// ============================================================================
+
+////
+/// 
+/// Unit Functions Module
+/// ===========================================================================
+/// 
+/// @group Unit
+/// @author Scape Agency
+/// @link https://unit.gl
+/// @since 0.1.0 initial release
+/// @todo None
+/// @access public
+/// 
+////
+
+
+// ============================================================================
+// Use
+// ============================================================================
+
+
+// ============================================================================
+// Forward
+// ============================================================================
+
+@forward "unit_conversion";   // Unit conversion functions
+@forward "unit_functions";    // Additional utility functions for units