Functions

@@use 'sass:math';
@@use 'sass:color';
@@use 'sass:list';
@@use 'sass:map';
@@use 'sass:string';

/* 1) Math module (replaces deprecated / division) */
$gap: math.div(16, 2);            // 8
$ratio: math.div(2, 3);             // 0.6667
$abs: math.abs(-5);                 // 5
$pct: math.percentage(0.3);         // 30%
$sqr: math.sqrt(25);                // 5
$rnd: math.round(3.7);              // 4
$max: math.max(2, 4, 6);            // 6
$min: math.min(2, 4, 6);            // 2
$clamp: math.clamp(0, 7, 5);        // 5

/* 2) Color module — modern color manipulation */
$primary: #0ea5e9;

.btn:hover  { background: color.adjust($primary, $lightness: -10%); }
.btn:active { background: color.adjust($primary, $lightness: -20%); }
.subtle     { color:      color.adjust($primary, $alpha: -0.5); }
.brighter   { background: color.scale($primary,  $lightness: 20%); }
.tinted     { background: color.mix($primary, white, 70%); }
.contrast   { color:      if(color.channel($primary, 'lightness', $space: oklch) > 60%, #000, #fff); }

/* 3) List module */
$sizes: 4, 8, 12, 16, 24;
list.length($sizes)                  // 5
list.nth($sizes, 2)                  // 8
list.append($sizes, 32)              // 4, 8, 12, 16, 24, 32
list.join($sizes, (40, 48))          // 4, 8, 12, 16, 24, 40, 48

/* 4) Map module */
$theme: ('primary': #0ea5e9, 'danger': #ef4444, 'success': #10b981);
map.get($theme, 'primary')           // #0ea5e9
map.has-key($theme, 'warning')       // false
map.merge($theme, ('warning': #f59e0b))
map.keys($theme)                     // primary, danger, success
map.values($theme)                   // #0ea5e9, #ef4444, #10b981

/* 5) String module */
string.length('hello')                // 5
string.to-upper-case('hello')         // 'HELLO'
string.slice('hello world', 1, 5)     // 'hello'
string.index('foo-bar', '-')          // 4
string.insert('foo', '-bar', 4)       // 'foo-bar'

/* 6) Custom function — px → rem */
@@function rem($px) {
    @@return math.div($px, 16) * 1rem;
}

.heading { font-size: rem(28); }   // 1.75rem

/* 7) Type scale generator — modular ratio */
$base-size: 1rem;
$ratio: 1.25;        // major third

@@function step($n) {
    @@return math.pow($ratio, $n) * $base-size;
}

.text-sm   { font-size: step(-1); }   // ~0.8rem
.text-base { font-size: step(0);  }   // 1rem
.text-lg   { font-size: step(1);  }   // 1.25rem
.text-xl   { font-size: step(2);  }   // ~1.56rem
.text-2xl  { font-size: step(3);  }   // ~1.95rem

/* 8) Strip the unit from a value */
@@function strip-unit($value) {
    @@return math.div($value, ($value * 0 + 1));
}

/* 9) Token lookup with fallback */
$tokens: (
    color: ('primary': #0ea5e9, 'success': #10b981),
    space: ('sm': 0.5rem, 'md': 1rem, 'lg': 1.5rem),
);

@@function token($path, $fallback: null) {
    $value: $tokens;
    @@each $key in ($path) {
        @@if map.has-key($value, $key) {
            $value: map.get($value, $key);
        } @@else {
            @@return $fallback;
        }
    }
    @@return $value;
}

.btn-primary { background: token((color, primary)); padding: token((space, md)); }

/* 10) Color contrast — pick black/white for accessibility */
@@function on($bg) {
    @@if (color.channel($bg, 'lightness', $space: hsl) > 50%) {
        @@return #111;
    } @@else {
        @@return #fff;
    }
}

.btn { background: $primary; color: on($primary); }

/* 11) Generate breakpoint map at compile-time */
$bp: ('sm': 640px, 'md': 768px, 'lg': 1024px, 'xl': 1280px);

@@mixin breakpoint($name) {
    $value: map.get($bp, $name);
    @@if not $value { @@error "Unknown breakpoint: #{$name}"; }
    @@media (min-width: $value) { @@content; }
}

.container {
    padding: 1rem;
    @@include breakpoint('md') { padding: 1.5rem; }
    @@include breakpoint('lg') { padding: 2rem; }
}

/* 12) Functions vs mixins */
/*   @@function returns a VALUE                                              */
/*   @@mixin emits RULES (declarations)                                      */
/*   Use function for one-value computation, mixin for blocks of declarations */

/* 13) DON'T duplicate built-ins */
/* The sass:math / sass:color modules already cover most needs.                */
/* Roll your own only when expressing a design-system intent that's not built-in. */

/* 14) Debug + error */
@@function brand($name) {
    $c: map.get($theme, $name);
    @@if not $c { @@warn "Unknown brand color '#{$name}', falling back to grey"; @@return #888; }
    @@return $c;
}

@function spacing($n) {
    @return $n * 4px;
}
.p-md { padding: spacing(4); }   // 16px