@zhang_jifan/fanui 2.1.0

package/src/_functions.scss

@@ -0,0 +1,319 @@
+// =============================================================================
+// fanUI · 工具函数层 (Functions)
+// -----------------------------------------------------------------------------
+// 所有函数统一以 `fanui-` 为前缀，纯函数、无副作用、不产生任何 CSS 输出。
+// 依赖：dart-sass >= 1.79（使用 color.channel 现代色彩 API，无弃用告警）
+// =============================================================================
+
+@use "sass:math";
+@use "sass:color";
+@use "sass:map";
+@use "sass:list";
+@use "sass:string";
+@use "sass:meta";
+
+// -----------------------------------------------------------------------------
+// 1. 数值处理
+// -----------------------------------------------------------------------------
+
+/// 去除数值单位。
+/// @example fanui-strip-unit(16px) => 16
+@function fanui-strip-unit($number) {
+  @if not math.is-unitless($number) {
+    @return math.div($number, $number * 0 + 1);
+  }
+  @return $number;
+}
+
+/// px 转 rem。
+/// @example fanui-px2rem(24px) => 1.5rem
+@function fanui-px2rem($px, $base: 16px) {
+  $base: fanui-strip-unit($base);
+  @if $base == 0 {
+    @error "fanUI: fanui-px2rem() 的 $base 不能为 0。";
+  }
+  @return math.div(fanui-strip-unit($px), $base) * 1rem;
+}
+
+/// rem 转 px。
+/// @example fanui-rem2px(1.5rem) => 24px
+@function fanui-rem2px($rem, $base: 16px) {
+  $base: fanui-strip-unit($base);
+  @return math.div(fanui-strip-unit($rem) * $base, 1) * 1px;
+}
+
+/// px 转 em（相对父级字号）。
+/// @example fanui-px2em(14px, 16px) => 0.875em
+@function fanui-px2em($px, $context: 16px) {
+  $context: fanui-strip-unit($context);
+  @if $context == 0 {
+    @error "fanUI: fanui-px2em() 的 $context 不能为 0。";
+  }
+  @return math.div(fanui-strip-unit($px), $context) * 1em;
+}
+
+/// 取负值（0 保持为 0，避免出现 `-0`）。
+@function fanui-negate($value) {
+  @if $value == 0 {
+    @return 0;
+  } @else {
+    @return -$value;
+  }
+}
+
+/// 百分比计算，返回 `%`。
+/// @example fanui-percentage(6, 12) => 50%
+@function fanui-percentage($value, $total) {
+  @if $total == 0 {
+    @error "fanUI: fanui-percentage() 的 $total 不能为 0。";
+  }
+  @return math.div(fanui-strip-unit($value), fanui-strip-unit($total)) * 100%;
+}
+
+/// 保留小数位。
+@function fanui-round($number, $digits: 2) {
+  $factor: math.pow(10, $digits);
+  @return math.div(math.round($number * $factor), $factor);
+}
+
+// -----------------------------------------------------------------------------
+// 2. 色彩处理
+// -----------------------------------------------------------------------------
+
+/// 设置颜色的透明度（现代 API，替代 rgba()）。
+/// @example fanui-alpha(#2563eb, 0.5) => rgba(37, 99, 235, 0.5)
+@function fanui-alpha($color, $alpha) {
+  @return color.change($color, $alpha: $alpha);
+}
+
+/// 变亮：与白色混合。
+/// @example fanui-tint(#2563eb, 20%) => 更浅的蓝
+@function fanui-tint($color, $weight: 20%) {
+  @return color.mix(#ffffff, $color, $weight);
+}
+
+/// 变暗：与黑色混合。
+@function fanui-shade($color, $weight: 20%) {
+  @return color.mix(#000000, $color, $weight);
+}
+
+/// 相对感知亮度（0~1），用于自动对比色计算。
+@function fanui-luminance($color) {
+  @if meta.type-of($color) != "color" {
+    @error "fanUI: fanui-luminance() 需要颜色值，收到 `#{$color}`。";
+  }
+
+  $r: math.div(color.channel($color, "red", $space: rgb), 255);
+  $g: math.div(color.channel($color, "green", $space: rgb), 255);
+  $b: math.div(color.channel($color, "blue", $space: rgb), 255);
+
+  @if $r <= 0.03928 {
+    $r: math.div($r, 12.92);
+  } @else {
+    $r: math.pow(math.div($r + 0.055, 1.055), 2.4);
+  }
+
+  @if $g <= 0.03928 {
+    $g: math.div($g, 12.92);
+  } @else {
+    $g: math.pow(math.div($g + 0.055, 1.055), 2.4);
+  }
+
+  @if $b <= 0.03928 {
+    $b: math.div($b, 12.92);
+  } @else {
+    $b: math.pow(math.div($b + 0.055, 1.055), 2.4);
+  }
+
+  @return 0.2126 * $r + 0.7152 * $g + 0.0722 * $b;
+}
+
+/// 依据背景色自动返回可读的前景色（深色或浅色）。
+/// @example fanui-contrast(#000) => #ffffff
+@function fanui-contrast($background, $light: #ffffff, $dark: #0f172a, $threshold: 0.4) {
+  @if fanui-luminance($background) > $threshold {
+    @return $dark;
+  }
+  @return $light;
+}
+
+/// 依据背景色返回「弱化前景色」（次级文本）。
+@function fanui-contrast-muted($background, $light: rgba(#ffffff, 0.72), $dark: rgba(#0f172a, 0.66), $threshold: 0.4) {
+  @if fanui-luminance($background) > $threshold {
+    @return $dark;
+  }
+  @return $light;
+}
+
+/// 两色之间的插值（t: 0~1）。
+@function fanui-mix($from, $to, $t: 0.5) {
+  @return color.mix($to, $from, fanui-round($t * 100, 2) * 1%);
+}
+
+/// 是否判定为「深色」。阈值 0.179 是 WCAG 里黑/白前景对比度相等点。
+@function fanui-is-dark($color, $threshold: 0.179) {
+  @return fanui-luminance($color) < $threshold;
+}
+
+/// WCAG 2.1 对比度（1 ~ 21）。
+/// @example fanui-contrast-ratio(#fff, #000) => 21
+@function fanui-contrast-ratio($a, $b) {
+  $la: fanui-luminance($a);
+  $lb: fanui-luminance($b);
+  @if $la < $lb {
+    $tmp: $la;
+    $la: $lb;
+    $lb: $tmp;
+  }
+  @return math.div($la + 0.05, $lb + 0.05);
+}
+
+/// 在浅色 / 深色墨色中择优，返回对比度更高的前景色（保证最大可读性）。
+/// 这是「自动可获得性」的核心：任何品牌色都能得到合规前景色。
+/// @example fanui-best-fg(#06b6d4) => #0b1220
+@function fanui-best-fg($bg, $light: #ffffff, $dark: #0b1220) {
+  @if fanui-contrast-ratio($bg, $light) >= fanui-contrast-ratio($bg, $dark) {
+    @return $light;
+  }
+  @return $dark;
+}
+
+/// 只有当「白色前景」达到 $min-ratio 时才返回 $light，否则返回 $dark。
+/// 用于需要固定「白字」语义的实心按钮等场景。
+@function fanui-white-fg-or($bg, $min-ratio: 4.5, $light: #ffffff, $dark: #0b1220) {
+  @if fanui-contrast-ratio($bg, $light) >= $min-ratio {
+    @return $light;
+  }
+  @return $dark;
+}
+
+/// 在候选色阶中择优：返回第一个满足对比度要求的色阶键。
+/// 用于「主题色自动挑选合规主色阶」——浅色模式偏爱深阶、深色模式偏爱浅阶。
+/// @example fanui-pick-tone((500: #06b6d4, 600: #0891b2, 700: #0e7490), (600, 700))
+@function fanui-pick-tone($tones, $candidates, $min-ratio: 4.5, $against: #ffffff, $fallback: null) {
+  @each $name in $candidates {
+    @if map.has-key($tones, $name) {
+      $color: map.get($tones, $name);
+      @if fanui-contrast-ratio($color, $against) >= $min-ratio {
+        @return $name;
+      }
+    }
+  }
+  @if $fallback != null {
+    @return $fallback;
+  }
+  @return list.nth($candidates, 1);
+}
+
+/// 色相旋转（HSL 空间），用于派生辅助色 / 装饰色。
+/// @example fanui-hue-shift(#0891b2, 40deg)
+@function fanui-hue-shift($color, $deg) {
+  @return color.adjust($color, $hue: $deg, $space: hsl);
+}
+
+/// 饱和度调整（HSL 空间）。
+@function fanui-saturate-color($color, $amount) {
+  @return color.adjust($color, $saturation: $amount, $space: hsl);
+}
+
+/// 明度调整（HSL 空间）。
+@function fanui-lighten($color, $amount) {
+  @return color.adjust($color, $lightness: $amount, $space: hsl);
+}
+
+/// 依据模式推导「悬停色」：浅色模式压暗、深色模式提亮。
+@function fanui-state-color($color, $mode: light, $amount: 8%) {
+  @if $mode == dark {
+    @return fanui-tint($color, $amount);
+  }
+  @return fanui-shade($color, $amount);
+}
+
+// -----------------------------------------------------------------------------
+// 3. Map / 设计令牌读取
+// -----------------------------------------------------------------------------
+
+/// 安全地深层读取 map 值，路径不存在时抛出可定位的错误。
+/// @example fanui-map-deep($colors, "primary", 500)
+@function fanui-map-deep($map, $keys...) {
+  $cursor: $map;
+  @each $key in $keys {
+    @if meta.type-of($cursor) != "map" or not map.has-key($cursor, $key) {
+      @error "fanUI: 在令牌表中找不到路径 `#{list.join($keys, ' > ')}`（当前键：#{$key}）。";
+    }
+    $cursor: map.get($cursor, $key);
+  }
+  @return $cursor;
+}
+
+/// 读取调色板色阶：fanui-palette($colors, primary, 500)
+@function fanui-palette($palette, $name, $tone: 500) {
+  @return fanui-map-deep($palette, $name, $tone);
+}
+
+/// 读取间距令牌：fanui-space($spacers, 4)
+@function fanui-space($spacers, $key) {
+  @return fanui-map-deep($spacers, $key);
+}
+
+/// 读取字号令牌。
+@function fanui-font-size($sizes, $key) {
+  @return fanui-map-deep($sizes, $key);
+}
+
+/// 读取断点值。
+@function fanui-breakpoint($breakpoints, $name) {
+  @return fanui-map-deep($breakpoints, $name);
+}
+
+/// 生成 keyframes / class 名安全化：替换 `.` 与 `%`。
+@function fanui-slug($value) {
+  $s: "#{$value}";
+  $s: string.replace($s, ".", "-");
+  $s: string.replace($s, "%", "p");
+  @return $s;
+}
+
+// -----------------------------------------------------------------------------
+// 4. CSS 自定义属性引用
+// -----------------------------------------------------------------------------
+
+/// 生成 `var(--fanui-*)` 引用，可带兜底值。
+/// @example fanui-var("color-primary") => var(--fanui-color-primary)
+/// @example fanui-var("radius", 6px)   => var(--fanui-radius, 6px)
+@function fanui-var($name, $fallback: null) {
+  @if $fallback == null {
+    @return var(--fanui-#{$name});
+  }
+  @return var(--fanui-#{$name}, #{$fallback});
+}
+
+/// 生成带命名空间的 `var()`（多级令牌，如 --fanui-color-primary-500）。
+@function fanui-var-ns($names...) {
+  @return var(--fanui-#{list.join($names, "-")});
+}
+
+/// 生成 `calc()` 表达式，自动处理单位。
+/// @example fanui-calc("100%", "-", 24px) => calc(100% - 24px)
+@function fanui-calc($a, $op, $b) {
+  @return calc(#{$a} #{$op} #{$b});
+}
+
+/// 生成尺寸简写。
+@function fanui-size-value($value) {
+  @if $value == null or $value == 0 {
+    @return 0;
+  } @else {
+    @return $value;
+  }
+}
+
+/// 生成断点中缀（用于拼接响应式类名）。
+/// @example fanui-bp-infix("md") => "-md"；fanui-bp-infix("xs") => ""
+@function fanui-bp-infix($name) {
+  @if $name == "xs" {
+    @return "";
+  } @else {
+    @return "-#{$name}";
+  }
+}