Math & Units

// 1) Always @use the module — NEVER @import sass:math
@use 'sass:math';

// 2) Division — math.div replaces /
$width: math.div(100%, 3);              // 33.3333%
$rems:  math.div(16px, 1rem);           // 16   (unitless)
$gap:   math.div($total, 12);          // pixels / 12

// The legacy '/' division operator is DEPRECATED. Use math.div for divisions; '/' inside shorthand
// like font/border/etc. remains as a separator.

// 3) Multiplication + addition work as expected (unit-aware)
$double: 16px * 2;          // 32px
$sum:    16px + 4px;        // 20px
$mixed:  16px + 2rem;       // ERROR — incompatible units

// 4) Common helpers
math.percentage(0.25);       // 25%
math.percentage(math.div(3, 4));   // 75%
math.round(3.6);              // 4
math.floor(3.6);              // 3
math.ceil(3.1);                // 4
math.abs(-5);                  // 5
math.min(10, 5, 20);          // 5
math.max(10, 5, 20);          // 20

// 5) Power + roots
math.pow(2, 10);              // 1024
math.sqrt(144);                // 12   (math.sqrt added in Dart Sass 1.25.0)

// 6) Logarithms
math.log(100, 10);            // 2   (log base 10)
math.log($x);                 // natural log

// 7) Trigonometry — useful for fluid + geometric math
math.sin(45deg);              // 0.7071
math.cos(60deg);              // 0.5
math.tan(30deg);              // 0.5774
math.atan2(1, 1);              // 45deg

// Useful for: hexagon layouts, polar coordinates, parallax math, easing curves

// 8) Unit utilities
math.unit(16px);              // 'px'
math.is-unitless(16);          // true
math.is-unitless(16px);        // false
math.compatible(16px, 1rem);   // false  (different unit families)
math.compatible(16px, 1cm);    // true (both lengths)

// 9) Stripping units
@function strip-unit($value) {
    @return math.div($value, ($value * 0 + 1));
}
strip-unit(16px);             // 16
strip-unit(2rem);              // 2

// Modern Dart Sass alternative:
// math.div(16px, 1px) → 16

// 10) Adding units to a number
@function px($value) { @return $value * 1px; }
@function rem($value) { @return $value * 1rem; }
px(16);                       // 16px
rem(1.5);                     // 1.5rem

// 11) Real-world: fluid type with clamp + math
@function fluid-clamp($min, $max, $min-vw: 320, $max-vw: 1440) {
    $slope: math.div($max - $min, $max-vw - $min-vw);
    $base:  $min - $slope * $min-vw;
    @return clamp(#{rem($min)}, #{$base * 1px} + #{math.percentage($slope)} * 100vw, #{rem($max)});
}

h1 { font-size: fluid-clamp(28, 48); }

// 12) Aspect-ratio padding (legacy pre-aspect-ratio CSS)
@function ratio-padding($ratio) {
    @return math.percentage(math.div(1, $ratio));
}
.video-16-9 { padding-top: ratio-padding(math.div(16, 9)); }

// 13) Color stop interpolation
@function color-mix($a, $b, $weight) {
    @return mix($a, $b, math.percentage($weight));
}

// 14) Random + clamping
math.random();                // 0..1 (with no seed)
math.random(100);             // 1..100 integer
math.clamp(10, 50, 100);      // returns 50 (clamped between 10..100)

// 15) Generating utility scales programmatically
@for $i from 0 through 12 {
    .p-#{$i} { padding: math.div($i, 4) * 1rem; }   // p-0..p-12 → 0..3rem
    .gap-#{$i} { gap: math.div($i, 4) * 1rem; }
}

// 16) Common bugs
// • Using '/' for division → silent string concat ('100% / 3' becomes literal); switch to math.div
// • Mixed unit operations → 'Incompatible units' error; convert first
// • math.div with two units of the same family → result is UNITLESS (the units cancel)
//     math.div(16px, 8px) → 2
//     math.div(16px, 8)   → 2px
// • Forgetting units after dividing → 'invalid CSS' downstream; multiply back by 1px etc
// • Trig in degrees vs radians — Sass uses the unit you supply (deg, rad, grad, turn)
// • Random without seed → different output every build; pin via env if needed
// • Logarithm with base 0 → error
// • Trying math.div on COLOR — only numbers and number-like (with units) work

@use 'sass:math';
width: math.div(100%, 3);
height: math.percentage(0.25);