katanakit-js 6.2.0 → 6.6.1

package/scss/_functions.scss

@@ -0,0 +1,168 @@
+// ============================================================
+//  _functions.scss
+//  Pure Sass functions: unit conversion, color manipulation and
+//  fluid typography. They emit no CSS by themselves — use them
+//  inside your own rules or mixins.
+// ============================================================
+@use "sass:math";
+@use "sass:color";
+@use "sass:meta";
+@use "sass:string";
+@use "sass:list";
+
+// Root font-size. Must match the --root-font-size you set in the reset
+// (62.5% → 10px on 16px browsers). This makes 1rem = 10px, so rem()
+// and px() produce values where rem ≈ px.
+// Override before importing this module (!default semantics).
+$base-font-size: 10px !default;
+
+// ============================================================
+//  PRIVATE HELPERS
+// ============================================================
+
+// Recursively replaces every occurrence of $search inside $string.
+// Used by to-class() to escape CSS selectors.
+@function _str-replace($string, $search, $replace: "") {
+  $index: string.index($string, $search);
+  @if not $index { @return $string; }
+  @return string.slice($string, 1, $index - 1) + $replace +
+    _str-replace(string.slice($string, $index + string.length($search)), $search, $replace);
+}
+
+// ============================================================
+//  UNIT CONVERSION
+//  Convert between px, rem and other CSS units.
+//  All conversions respect $base-font-size (default 10px).
+// ============================================================
+
+// Convert a px value to rem. Accepts unitless numbers (treated as px)
+// or values with a px unit.
+// Example: f.rem(16px) → 1.6rem (16 / 10).
+@function rem($size) {
+  @if meta.type-of($size) != "number" {
+    @error "rem(): se esperaba un número, recibió #{meta.inspect($size)}.";
+  }
+  $px: if(sass(math.is-unitless($size)): $size; else: math.div($size, 1px));
+  $base: math.div($base-font-size, 1px);
+  @return math.div($px, $base) * 1rem;
+}
+
+// Convert a rem value to px. Unitless numbers are treated as rem.
+// Example: f.px(1.6rem) → 16px (1.6 * 10).
+@function px($size) {
+  @if meta.type-of($size) != "number" {
+    @error "px(): se esperaba un número, recibió #{meta.inspect($size)}.";
+  }
+  $num: if(sass(math.is-unitless($size)): $size; else: math.div($size, 1rem));
+  $base: math.div($base-font-size, 1px);
+  @return $num * $base * 1px;
+}
+
+// Append a unit to a unitless number (values that already have a
+// unit are returned unchanged). Valid units: rem, px, em, %.
+// Example: f.to-unit(4, "rem") → 4rem.
+@function to-unit($value, $unit: "rem") {
+  @if meta.type-of($value) != "number" {
+    @error "to-unit(): se esperaba un número, recibió #{meta.inspect($value)}.";
+  }
+  @if not math.is-unitless($value) { @return $value; }
+  $valid: ("rem", "px", "em", "%");
+  @if not list.index($valid, $unit) {
+    @error "to-unit(): unidad '#{$unit}' no válida. Use: rem, px, em, %.";
+  }
+  @if $unit == "rem" { @return $value * 1rem; }
+  @if $unit == "px"  { @return $value * 1px; }
+  @if $unit == "em"  { @return $value * 1em; }
+  @if $unit == "%"   { @return $value * 1%; }
+  @error "to-unit(): caso no cubierto para '#{$unit}'.";
+}
+
+// Remove the unit from a number by dividing by its own unit.
+// Example: f.strip-unit(16px) → 16.
+@function strip-unit($value) {
+  @if meta.type-of($value) != "number" { @error "strip-unit(): se esperaba un número."; }
+  @return math.div($value, ($value * 0 + 1));
+}
+
+// ============================================================
+//  FLUID TYPOGRAPHY (clamp)
+// ============================================================
+
+// Builds a clamp() value that scales linearly from $min at
+// $min-vw viewport width to $max at $max-vw. Unitless numbers are
+// treated as px. Uses the classic slope/intercept formula:
+// preferred = slope * 100vw ± intercept, clamped between min and max.
+// Example: f.fluid(16, 24) →
+//   clamp(16px, 0.5vw + 14.4px, 24px) between 320px and 1920px.
+@function fluid($min, $max, $min-vw: 320px, $max-vw: 1920px) {
+  $min-val: if(sass(math.is-unitless($min)): $min * 1px; else: $min);
+  $max-val: if(sass(math.is-unitless($max)): $max * 1px; else: $max);
+  $vw-min: if(sass(math.is-unitless($min-vw)): $min-vw * 1px; else: $min-vw);
+  $vw-max: if(sass(math.is-unitless($max-vw)): $max-vw * 1px; else: $max-vw);
+
+  $slope: math.div(
+    strip-unit($max-val) - strip-unit($min-val),
+    strip-unit($vw-max) - strip-unit($vw-min)
+  );
+  $intercept: strip-unit($min-val) - ($slope * strip-unit($vw-min));
+
+  $sign: if(sass($intercept >= 0): "+"; else: "-");
+  $preferred: #{$slope * 100}vw #{$sign} #{math.abs($intercept)}px;
+
+  @return clamp(#{$min-val}, #{$preferred}, #{$max-val});
+}
+
+// ============================================================
+//  COLOR MANIPULATION
+// ============================================================
+
+// Mix a color toward white. $amount is a percentage (unitless
+// numbers are treated as %). f.tint($c, 20%) = 20% white + 80% $c.
+@function tint($color, $amount: 10%) {
+  @if meta.type-of($color) != "color" { @error "tint(): se esperaba un color."; }
+  $pct: if(sass(math.is-unitless($amount)): $amount * 1%; else: $amount);
+  @return color.mix(white, $color, $pct);
+}
+
+// Mix a color toward black. Inverse of tint().
+@function shade($color, $amount: 10%) {
+  @if meta.type-of($color) != "color" { @error "shade(): se esperaba un color."; }
+  $pct: if(sass(math.is-unitless($amount)): $amount * 1%; else: $amount);
+  @return color.mix(black, $color, $pct);
+}
+
+// Scale saturation up/down by $amount percentage points.
+@function saturate-color($color, $amount: 10%) { @return color.scale($color, $saturation: $amount); }
+@function desaturate-color($color, $amount: 10%) { @return color.scale($color, $saturation: -$amount); }
+// Hue-rotate the color by 180° (the complementary color).
+@function complement($color) { @return color.complement($color); }
+
+// Returns black or white (or your own pair) depending on which has
+// better contrast against $color, using perceptual luminance weights
+// (0.299/0.587/0.114). Bright colors return $dark, dark ones $light.
+@function contrast($color, $light: white, $dark: black) {
+  $brightness: (color.red($color) * 0.299 + color.green($color) * 0.587 + color.blue($color) * 0.114) / 255;
+  @return if(sass($brightness > 0.5): $dark; else: $light);
+}
+
+// Builds a CSS color-mix() that blends a custom property with
+// another color at runtime. $var-name is accepted with or without
+// the var() wrapper. Example:
+// f.color-mix-var(--purple-500, 20%) →
+//   color-mix(in srgb, var(--purple-500) 80%, white).
+@function color-mix-var($var-name, $amount: 10%, $mix-with: white) {
+  $name: if(sass(string.index($var-name, "var(") == 1): $var-name; else: "var(#{$var-name})");
+  $pct: if(sass(math.is-unitless($amount)): $amount * 1%; else: $amount);
+  $color-pct: 100% - $pct;
+  @return color-mix(in srgb, #{$name} #{$color-pct}, #{$mix-with});
+}
+
+// Escapes characters that are invalid in CSS class selectors
+// ('.', '/', '%') so a token key can be used as a class name.
+@function to-class($key) {
+  $str: "#{$key}";
+  $str: _str-replace($str, ".", "\\.");
+  $str: _str-replace($str, "/", "\\/");
+  $str: _str-replace($str, "%", "\\%");
+  @return $str;
+}