Utilities

/**
 * Increments up or down a defined scale and returns an adjusted value
 * @param $increment - How many steps to increment up or down the scale (unitless number)
 * @param $value - The base value the scale starts at (number with unit or list, optional)
 * @param $ratio - The ratio the scale is built on (unitless number, optional)
 * @returns number (with unit) - The calculated scale value
 * @requires _fetch-bourbon-setting function
 */
@function modular-scale(
  $increment,
  $value: _fetch-bourbon-setting("modular-scale-base"),
  $ratio: _fetch-bourbon-setting("modular-scale-ratio")
): number;

// Basic usage with default settings
.element {
  font-size: modular-scale(2);
  // Result: 1.5625em (assuming 1em base and 1.25 ratio)
}

// Custom base value
.element {
  margin-right: modular-scale(3, 2em);
  // Result: 3.90625em
}

// Custom base and ratio
.element {
  font-size: modular-scale(3, 1em 1.6em, $major-seventh);
  // Result: 3em
}

// Negative increments for smaller values
.small-text {
  font-size: modular-scale(-1);
  // Result: 0.8em (with default 1.25 ratio)
}

// Creating a typography scale
$base-font-size: 1rem;
$scale-ratio: $perfect-fourth;

.text-xs { font-size: modular-scale(-2, $base-font-size, $scale-ratio); }
.text-sm { font-size: modular-scale(-1, $base-font-size, $scale-ratio); }
.text-base { font-size: $base-font-size; }
.text-lg { font-size: modular-scale(1, $base-font-size, $scale-ratio); }
.text-xl { font-size: modular-scale(2, $base-font-size, $scale-ratio); }
.text-2xl { font-size: modular-scale(3, $base-font-size, $scale-ratio); }

/**
 * Strips the unit from a number
 * @param $value - Number with or without unit
 * @returns number (unitless) - The numeric value without units
 */
@function strip-unit($value): number;

// Basic usage
$dimension: strip-unit(10em);
// Result: 10

// Use in calculations
$base-width: 320px;
$unitless-width: strip-unit($base-width);
$columns: $unitless-width / 16; // 20 columns

// Convert between units
@function px-to-rem($px-value, $base: 16px) {
  @return (strip-unit($px-value) / strip-unit($base)) * 1rem;
}

.element {
  font-size: px-to-rem(18px); // 1.125rem
}

// Conditional logic based on numeric value
@function scale-font($size) {
  $unitless-size: strip-unit($size);
  
  @if $unitless-size > 24 {
    @return $size * 0.9; // Slightly smaller for large text
  } @else {
    @return $size;
  }
}

/**
 * Provides clearfix for containing floats
 * Uses modern clearfix technique with pseudo-elements
 */
@mixin clearfix;

// Basic clearfix
.container {
  @include clearfix;
  // Result:
  // &::after {
  //   clear: both;
  //   content: "";
  //   display: block;
  // }
}

// Float-based layout (legacy)
.float-layout {
  @include clearfix;
  
  .sidebar {
    float: left;
    width: 25%;
  }
  
  .content {
    float: right;
    width: 75%;
  }
}

// Print layouts
@media print {
  .print-section {
    @include clearfix;
    page-break-inside: avoid;
  }
}

/**
 * Generates CSS triangles using borders
 * @param $direction - Triangle direction ("up", "up-right", "right", "down-right", "down", "down-left", "left", "up-left")
 * @param $width - Triangle width (number with unit)
 * @param $height - Triangle height (number with unit)
 * @param $color - Triangle color
 */
@mixin triangle($direction, $width, $height, $color);

// Basic triangle
.arrow-up {
  @include triangle("up", 2rem, 1rem, #b25c9c);
  // Result: Creates upward-pointing triangle
}

// Tooltip arrow
.tooltip {
  position: relative;
  
  &::after {
    content: "";
    position: absolute;
    top: 100%;
    left: 50%;
    margin-left: -8px;
    @include triangle("down", 16px, 8px, #333);
  }
}

// Navigation arrows
.carousel-prev::before {
  content: "";
  @include triangle("left", 12px, 20px, #007acc);
}

.carousel-next::after {
  content: "";
  @include triangle("right", 12px, 20px, #007acc);
}

// Breadcrumb separators
.breadcrumb-item:not(:last-child)::after {
  content: "";
  @include triangle("right", 8px, 8px, #666);
  margin: 0 0.5rem;
  display: inline-block;
}

// Diagonal triangles for corners
.corner-triangle {
  position: relative;
  
  &::before {
    content: "";
    position: absolute;
    top: 0;
    right: 0;
    @include triangle("down-left", 20px, 20px, #ff6b6b);
  }
}

/**
 * Generates vendor prefixes for properties
 * @param $property - CSS property to prefix
 * @param $value - Value to use for the property
 * @param $prefixes - List of vendor prefixes to output ("webkit", "moz", "ms", "o")
 */
@mixin prefixer($property, $value, $prefixes);

// Basic prefixing
.element {
  @include prefixer(appearance, none, ("webkit", "moz"));
  // Result:
  // -webkit-appearance: none;
  // -moz-appearance: none;
  // appearance: none;
}

// Transform prefixing
.animated {
  @include prefixer(transform, translateX(100px), ("webkit", "moz", "ms"));
  // Result:
  // -webkit-transform: translateX(100px);
  // -moz-transform: translateX(100px);
  // -ms-transform: translateX(100px);
  // transform: translateX(100px);
}

// Flexbox prefixing
.flex-container {
  @include prefixer(display, flex, ("webkit", "moz"));
  @include prefixer(flex-direction, column, ("webkit", "moz"));
}

/**
 * Generates vendor prefixes for values
 * @param $property - CSS property name
 * @param $value - Value to prefix
 * @param $prefixes - List of vendor prefixes to output ("webkit", "moz", "ms", "o")
 */
@mixin value-prefixer($property, $value, $prefixes);

// Cursor prefixing
.grabbable {
  @include value-prefixer(cursor, grab, ("webkit", "moz"));
  // Result:
  // cursor: -webkit-grab;
  // cursor: -moz-grab;
  // cursor: grab;
}

// Background gradient prefixing
.gradient {
  @include value-prefixer(
    background-image,
    linear-gradient(to bottom, #fff, #000),
    ("webkit", "moz")
  );
}

// Filter effects
.blurred {
  @include value-prefixer(filter, blur(5px), ("webkit"));
}

$bourbon: (
  "modular-scale-base": 1rem,        // Base value for modular scale
  "modular-scale-ratio": $major-third // Ratio for modular scale (1.25)
);

// Create responsive type scale
$base-font-mobile: 14px;
$base-font-desktop: 16px;
$scale-ratio: $perfect-fourth;

// Mobile-first typography
.heading-1 {
  font-size: modular-scale(3, $base-font-mobile, $scale-ratio);
  
  @media (min-width: 768px) {
    font-size: modular-scale(3, $base-font-desktop, $scale-ratio);
  }
}

// Convert pixels to rems
@function px-to-rem($px, $base: 16px) {
  @return (strip-unit($px) / strip-unit($base)) * 1rem;
}

// Convert rems to pixels
@function rem-to-px($rem, $base: 16px) {
  @return strip-unit($rem) * strip-unit($base) * 1px;
}

// Usage
.element {
  padding: px-to-rem(24px); // 1.5rem
  margin: rem-to-px(2rem);  // 32px
}

// Speech bubble with triangle tail
.speech-bubble {
  position: relative;
  background: #f0f0f0;
  border-radius: 8px;
  padding: 1rem;
  
  // Triangle tail
  &::after {
    content: "";
    position: absolute;
    bottom: -10px;
    left: 20px;
    @include triangle("down", 20px, 10px, #f0f0f0);
  }
}

// Multi-directional arrows
@each $direction in ("up", "right", "down", "left") {
  .arrow-#{$direction} {
    @include triangle($direction, 16px, 16px, currentColor);
    display: inline-block;
  }
}

// Comprehensive flexbox support
.flex-container {
  @include prefixer(display, flex, ("webkit", "moz"));
  @include prefixer(flex-direction, row, ("webkit", "moz"));
  @include prefixer(justify-content, space-between, ("webkit", "moz"));
  
  // Fallback for older browsers
  @include clearfix;
  
  .flex-item {
    @include prefixer(flex, 1, ("webkit", "moz"));
    
    // Fallback
    float: left;
    width: calc(100% / 3);
  }
}

// Invalid modular scale increment
.invalid {
  font-size: modular-scale("not-a-number");
  // Error: Invalid increment value
}

// Invalid triangle direction
.also-invalid {
  @include triangle("invalid-direction", 10px, 10px, red);
  // Error: Invalid triangle direction
}