@cloudcome/utils-core 0.0.0 → 1.1.1

package/src/color/hex-rgb.ts

@@ -0,0 +1,39 @@
+import type { HEX, RGB } from './types';
+
+/**
+ * 将HEX颜色字符串转换为RGB颜色对象
+ * @param hex HEX颜色字符串，支持3位或6位格式（例如#f00或#ff0000）
+ * @returns {RGB} 对应的RGB颜色对象
+ * @throws {SyntaxError} 当颜色格式不符合规范时抛出
+ * @example
+ * hexToRgb('#f00') // returns {r: 255, g: 0, b: 0}
+ */
+export function hexToRgb(hex: HEX): RGB {
+  const reg = hex.length === 4 ? /^#(.)(.)(.)$/ : /^#(.{2})(.{2})(.{2})$/;
+  const result = reg.exec(hex);
+
+  if (!result) throw new SyntaxError(`颜色（${hex}）表达式有误`);
+
+  const [_, r, g, b] = result;
+
+  return {
+    r: Number.parseInt(r.padEnd(2, r), 16),
+    g: Number.parseInt(g.padEnd(2, g), 16),
+    b: Number.parseInt(b.padEnd(2, b), 16),
+  };
+}
+
+function to16(n: number) {
+  return Math.round(n).toString(16).padStart(2, '0');
+}
+
+/**
+ * 将RGB颜色对象转换为HEX颜色字符串
+ * @param rgb RGB颜色对象
+ * @returns {HEX} 6位HEX颜色字符串（带#前缀）
+ * @example
+ * rgbToHex({r: 255, g: 0, b: 0}) // returns '#ff0000'
+ */
+export function rgbToHex(rgb: RGB): HEX {
+  return `#${to16(rgb.r)}${to16(rgb.g)}${to16(rgb.b)}`;
+}

package/src/color/hsl-lighten.ts

@@ -0,0 +1,15 @@
+import type { HSL } from './types';
+
+/**
+ * 通过HSL颜色空间调整颜色亮度
+ * @param hsl 原始 HSL 颜色
+ * @param value 亮度调整系数（0-1之间，0.1表示增加10%亮度）
+ * @returns {HSL} 调整后的 HSL 颜色
+ * @example
+ * hslLighten({h: 300, s: 33, l: 44}, 0.2) // 返回亮度增加20%后的颜色
+ */
+export function hslLighten(hsl: HSL, value: number): HSL {
+  const hslFinal = { ...hsl };
+  hslFinal.l = hslFinal.l * (1 + value);
+  return hslFinal;
+}

package/src/color/hsv-brighten.ts

@@ -0,0 +1,17 @@
+import type { HSV } from './types';
+
+/**
+ * 通过HSV颜色空间调整颜色明度
+ * @param hsv 原始HSV颜色对象
+ * @param value 明度调整系数（-1到1之间）：
+ *   - 正值增加明度（如0.2表示+20%）
+ *   - 负值降低明度（如-0.1表示-10%）
+ * @returns {HSV} 调整后的HSV颜色对象（v值范围0-100%）
+ * @example
+ * hsvBrighten({h: 0, s: 100, v: 50}, 0.3) // 返回{h: 0, s: 100, v: 65}
+ */
+export function hsvBrighten(hsv: HSV, value: number): HSV {
+  const hsvFinal = { ...hsv };
+  hsvFinal.v = hsvFinal.v * (1 + value);
+  return hsvFinal;
+}

package/src/color/luminance.ts

@@ -0,0 +1,17 @@
+import type { RGB } from './types';
+
+/**
+ * 计算RGB颜色的相对亮度（符合WCAG 2.1标准）
+ * @param rgb RGB颜色对象（分量范围0-255）
+ * @returns {number} 相对亮度值（0-1之间）
+ * @see https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
+ * @example
+ * luminance({r: 255, g: 255, b: 255}) // 返回1
+ */
+export function luminance({ r, g, b }: RGB) {
+  const a = [r, g, b].map((v) => {
+    const vFinal = v / 255;
+    return vFinal <= 0.03928 ? vFinal / 12.92 : ((vFinal + 0.055) / 1.055) ** 2.4;
+  });
+  return a[0] * 0.2126 + a[1] * 0.7152 + a[2] * 0.0722;
+}

package/src/color/mix.ts

@@ -0,0 +1,26 @@
+import type { HSL, HSV, RGB } from './types';
+
+/**
+ * 颜色混合函数（支持RGB/HSL/HSV色彩模型）
+ * @template T 颜色类型，支持RGB、HSL或HSV对象
+ * @param {T} a 第一个颜色对象
+ * @param {T} b 第二个颜色对象
+ * @param {number} [weight=0.5] 混合权重（0-1之间）：
+ *   - 0 表示完全使用第一个颜色
+ *   - 1 表示完全使用第二个颜色
+ * @returns {T} 线性混合后的新颜色对象
+ * @example
+ * // RGB混合示例
+ * mix({r: 255, g: 0, b: 0}, {r: 0, g: 0, b: 255}, 0.5) // 返回紫色
+ *
+ * // HSL混合示例
+ * mix({h: 0, s: 100, l: 50}, {h: 120, s: 100, l: 50}, 0.3)
+ */
+export function mix<T extends RGB | HSV | HSL>(a: T, b: T, weight = 0.5): T {
+  return Object.keys(a).reduce((acc, key) => {
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    acc[key] = (b[key] - a[key]) * weight + a[key];
+    return acc;
+  }, {} as T);
+}

package/src/color/rgb-hsl.ts

@@ -0,0 +1,53 @@
+// @ref https://www.w3schools.com/lib/w3color.js
+import { rgbToHue } from './helpers';
+import type { HSL, RGB } from './types';
+
+const { abs, min, max, round } = Math;
+
+/**
+ * 将RGB颜色转换为HSL颜色空间
+ * @param rgb RGB颜色对象（分量范围0-255）
+ * @returns {HSL} HSL颜色对象，其中：
+ *   h: 色相（0-360度）
+ *   s: 饱和度（0-100%）
+ *   l: 亮度（0-100%）
+ * @example
+ * rgbToHsl({r: 255, g: 0, b: 0}) // returns {h: 0, s: 100, l: 50}
+ */
+export function rgbToHsl(rgb: RGB): HSL {
+  const [hue, max, min, diff] = rgbToHue(rgb);
+  const l = (2 * max - diff) / 2;
+  const s = min === max ? 0 : l < 0.5 ? (max - min) / (max + min) : (max - min) / (2 - max - min);
+
+  return {
+    h: hue,
+    s: s * 100,
+    l: l * 100,
+  };
+}
+
+// @ref https://www.30secondsofcode.org/js/s/hsl-to-rgb/
+/**
+ * 将HSL颜色转换回RGB颜色空间
+ * @param hsl HSL颜色对象
+ * @param hsl.h 色相（0-360度）
+ * @param hsl.s 饱和度（0-100%）
+ * @param hsl.l 亮度（0-100%）
+ * @returns {RGB} RGB颜色对象（分量范围0-255）
+ * @example
+ * hslToRgb({h: 0, s: 100, l: 50}) // returns {r: 255, g: 0, b: 0}
+ */
+export function hslToRgb({ h, s, l }: HSL): RGB {
+  s /= 100;
+  l /= 100;
+
+  const a = s * min(l, 1 - l);
+  const k = (n: number) => (n + h / 30) % 12;
+  const f = (n: number) => l - a * max(-1, min(k(n) - 3, min(9 - k(n), 1)));
+
+  return {
+    r: 255 * f(0),
+    g: 255 * f(8),
+    b: 255 * f(4),
+  };
+}

package/src/color/rgb-hsv.ts

@@ -0,0 +1,52 @@
+import { rgbToHue } from './helpers';
+import type { HSV, RGB } from './types';
+
+const { abs, min, max, round } = Math;
+
+// @ref https://www.30secondsofcode.org/js/s/rgb-to-hsb/
+/**
+ * 将RGB颜色转换为HSV颜色空间
+ * @param rgb RGB颜色对象（分量范围0-255）
+ * @returns {HSV} HSV颜色对象：
+ *   h: 色相（0-360度）
+ *   s: 饱和度（0-100%）
+ *   v: 明度（0-100%）
+ * @see https://en.wikipedia.org/wiki/HSL_and_HSV
+ * @example
+ * rgbToHsv({r: 255, g: 0, b: 0}) // {h: 0, s: 100, v: 100}
+ */
+export function rgbToHsv(rgb: RGB): HSV {
+  const [hue, max, min, diff] = rgbToHue(rgb);
+
+  return {
+    h: hue,
+    s: max && (diff / max) * 100,
+    v: max * 100,
+  };
+}
+
+// @ref https://www.30secondsofcode.org/js/s/hsb-to-rgb/
+/**
+ * 将HSV颜色转换回RGB颜色空间
+ * @param hsv HSV颜色对象
+ * @param hsv.h 色相（0-360度）
+ * @param hsv.s 饱和度（0-100%）
+ * @param hsv.v 明度（0-100%）
+ * @returns {RGB} RGB颜色对象（分量范围0-255）
+ * @see https://www.rapidtables.com/convert/color/hsv-to-rgb.html
+ * @example
+ * hsvToRgb({h: 0, s: 100, v: 100}) // {r: 255, g: 0, b: 0}
+ */
+export function hsvToRgb({ h, s, v }: HSV): RGB {
+  s /= 100;
+  v /= 100;
+
+  const k = (n: number) => (n + h / 60) % 6;
+  const f = (n: number) => v * (1 - s * max(0, min(k(n), 4 - k(n), 1)));
+
+  return {
+    r: 255 * f(5),
+    g: 255 * f(3),
+    b: 255 * f(1),
+  };
+}

package/src/color/rgb-hwb.ts

@@ -0,0 +1,56 @@
+import { rgbToHue } from './helpers';
+import { hslToRgb } from './rgb-hsl';
+import type { HWB, RGB } from './types';
+
+/**
+ * 将RGB颜色转换为HWB颜色空间
+ * @param rgb RGB颜色对象（分量范围0-255）
+ * @returns {HWB} HWB颜色对象：
+ *   h: 色相（0-360度）
+ *   w: 白度（0-100%）
+ *   b: 黑度（0-100%）
+ * @see https://www.w3.org/TR/css-color-4/#hwb-to-rgb
+ * @example
+ * rgbToHwb({r: 255, g: 0, b: 0}) // {h: 0, w: 0, b: 0}
+ */
+export function rgbToHwb(rgb: RGB): HWB {
+  const [hue, max, min, diff] = rgbToHue(rgb);
+  return {
+    h: hue,
+    w: min * 100,
+    b: (1 - max) * 100,
+  };
+}
+
+// @ref https://www.w3schools.com/lib/w3color.js
+/**
+ * 将HWB颜色转换回RGB颜色空间
+ * @param hwb HWB颜色对象
+ * @param hwb.h 色相（0-360度）
+ * @param hwb.w 白度（0-100%）
+ * @param hwb.b 黑度（0-100%）
+ * @returns {RGB} RGB颜色对象（分量范围0-255）
+ * @see https://en.wikipedia.org/wiki/HWB_color_model
+ * @example
+ * hwbToRgb({h: 0, w: 0, b: 0}) // {r: 255, g: 0, b: 0}
+ */
+export function hwbToRgb({ h, w: white, b: black }: HWB) {
+  white /= 100;
+  black /= 100;
+
+  const { r, g, b } = hslToRgb({ h, s: 100, l: 50 });
+  const tot = white + black;
+
+  if (tot > 1) {
+    white = white / tot;
+    black = black / tot;
+  }
+
+  const f = (n: number) => ((n / 255) * (1 - white - black) + white) * 255;
+
+  return {
+    r: f(r),
+    g: f(g),
+    b: f(b),
+  };
+}

package/src/color/rgb-lab.ts

@@ -0,0 +1,33 @@
+import { rgbToXyz, xyzToRgb } from './rgb-xyz';
+import type { LAB, RGB } from './types';
+import { labToXyz, xyzToLab } from './xyz-lab';
+
+/**
+ * 将RGB颜色转换为Lab颜色空间（CIE 1976标准）
+ * @param rgb RGB颜色对象（分量范围0-255）
+ * @returns {LAB} Lab颜色对象：
+ *   l: 明度（0-100）
+ *   a: 绿-红分量（-128到127）
+ *   b: 蓝-黄分量（-128到127）
+ * @see https://en.wikipedia.org/wiki/CIELAB_color_space
+ * @example
+ * rgbToLab({r: 255, g: 0, b: 0}) // {l: 53.24, a: 80.09, b: 67.20}
+ */
+export function rgbToLab(rgb: RGB): LAB {
+  return xyzToLab(rgbToXyz(rgb));
+}
+
+/**
+ * 将Lab颜色转换回RGB颜色空间
+ * @param lab Lab颜色对象
+ * @param lab.l 明度（0-100）
+ * @param lab.a 绿-红分量（-128到127）
+ * @param lab.b 蓝-黄分量（-128到127）
+ * @returns {RGB} RGB颜色对象（分量可能超出0-255范围）
+ * @see https://www.easyrgb.com/en/math.php
+ * @example
+ * labToRgb({l: 53.24, a: 80.09, b: 67.20}) // {r: 255, g: 0, b: 0}
+ */
+export function labToRgb(lab: LAB): RGB {
+  return xyzToRgb(labToXyz(lab));
+}

package/src/color/rgb-whiter.ts

@@ -0,0 +1,22 @@
+import { mix } from './mix';
+import type { RGB } from './types';
+
+const { abs, min, max, round } = Math;
+
+const whiteRGB: RGB = { r: 0, g: 0, b: 0 };
+const blackRGB: RGB = { r: 255, g: 255, b: 255 };
+
+/**
+ * 通过混合颜色调整明暗度
+ * @param rgb 原始RGB颜色对象
+ * @param value 调整强度（-1到1之间）：
+ *   - 正值时与黑色混合（增加暗度）
+ *   - 负值时与白色混合（增加亮度）
+ * @returns {RGB} 调整后的RGB颜色对象
+ * @example
+ * rgbDarken({r: 100, g: 150, b: 200}, 0.2) // 变暗20%
+ */
+export function rgbWhiter(rgb: RGB, value: number): RGB {
+  const rgb2: RGB = value > 0 ? whiteRGB : blackRGB;
+  return mix(rgb, rgb2, abs(value));
+}

package/src/color/rgb-xyz.ts

@@ -0,0 +1,62 @@
+// https://stackoverflow.com/a/73998199
+
+import type { RGB, XYZ } from './types';
+
+/**
+ * 将RGB颜色转换为CIE 1931 XYZ颜色空间（D65白点，2°观察者）
+ * @param rgb RGB颜色对象（分量范围0-255）
+ * @returns {XYZ} XYZ颜色对象：
+ *   x: 约0-95.047
+ *   y: 约0-100.0
+ *   z: 约0-108.883
+ * @see https://en.wikipedia.org/wiki/CIE_1931_color_space
+ * @example
+ * rgbToXyz({r: 255, g: 255, b: 255}) // {x: 95.047, y: 100.0, z: 108.883}
+ */
+export function rgbToXyz(rgb: RGB): XYZ {
+  const { r, g, b } = rgb;
+  const [var_R, var_G, var_B] = [r, g, b]
+    .map((x) => x / 255)
+    .map((x) => (x > 0.04045 ? ((x + 0.055) / 1.055) ** 2.4 : x / 12.92))
+    .map((x) => x * 100);
+
+  return {
+    // Observer. = 2°, Illuminant = D65
+    x: var_R * 0.4124 + var_G * 0.3576 + var_B * 0.1805,
+    y: var_R * 0.2126 + var_G * 0.7152 + var_B * 0.0722,
+    z: var_R * 0.0193 + var_G * 0.1192 + var_B * 0.9505,
+  };
+}
+
+/**
+ * 将XYZ颜色转换回RGB颜色空间（可能超出常规范围）
+ * @param xyz XYZ颜色对象
+ * @returns {RGB} RGB颜色对象（分量可能超出0-255范围）
+ * @see https://www.brucelindbloom.com/index.html?Eqn_XYZ_to_RGB.html
+ * @example
+ * xyzToRgb({x: 95.047, y: 100.0, z: 108.883}) // {r: 255, g: 255, b: 255}
+ */
+export function xyzToRgb(xyz: XYZ): RGB {
+  const { x, y, z } = xyz;
+
+  //X, Y and Z input refer to a D65/2° standard illuminant.
+  //sR, sG and sB (standard RGB) output range = 0 ÷ 255
+
+  const var_X = x / 100;
+  const var_Y = y / 100;
+  const var_Z = z / 100;
+
+  const var_R = var_X * 3.2406 + var_Y * -1.5372 + var_Z * -0.4986;
+  const var_G = var_X * -0.9689 + var_Y * 1.8758 + var_Z * 0.0415;
+  const var_B = var_X * 0.0557 + var_Y * -0.204 + var_Z * 1.057;
+
+  const [r, g, b] = [var_R, var_G, var_B]
+    .map((n) => (n > 0.0031308 ? 1.055 * n ** (1 / 2.4) - 0.055 : 12.92 * n))
+    .map((n) => n * 255);
+
+  return {
+    r,
+    g,
+    b,
+  };
+}

package/src/color/types.ts

@@ -0,0 +1,65 @@
+/**
+ * HEX颜色字符串类型（带#前缀）
+ * @example "#ff0000" // 红色
+ * @example "#0f0"    // 绿色简写
+ */
+export type HEX = `#${string}`;
+
+/**
+ * RGB颜色空间类型
+ * @property r 红色分量（0-255）
+ * @property g 绿色分量（0-255）
+ * @property b 蓝色分量（0-255）
+ * @example {r: 255, g: 0, b: 0} // 纯红色
+ */
+export type RGB = { r: number; g: number; b: number };
+
+/**
+ * HSV/HSB颜色空间类型
+ * @property h 色相（0-360度）
+ * @property s 饱和度（0-100%）
+ * @property v 明度（0-100%）
+ * @see https://zh.wikipedia.org/wiki/HSL%E5%92%8CHSV%E8%89%B2%E5%BD%A9%E7%A9%BA%E9%97%B4
+ * @example {h: 0, s: 100, v: 100} // 纯红色
+ */
+export type HSV = { h: number; s: number; v: number };
+
+/**
+ * HSL颜色空间类型
+ * @property h 色相（0-360度）
+ * @property s 饱和度（0-100%）
+ * @property l 亮度（0-100%）
+ * @see https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/hsl
+ * @example {h: 120, s: 100, l: 50} // 纯绿色
+ */
+export type HSL = { h: number; s: number; l: number };
+
+/**
+ * HWB颜色空间类型（W3C标准）
+ * @property h 色相（0-360度）
+ * @property w 白度（0-100%）
+ * @property b 黑度（0-100%）
+ * @see https://zh.wikipedia.org/zh-hans/HWB%E8%89%B2%E5%BD%A9%E7%A9%BA%E9%97%B4
+ * @example {h: 0, w: 0, b: 0} // 纯红色
+ */
+export type HWB = { h: number; w: number; b: number };
+
+/**
+ * CIE LAB颜色空间类型（L*a*b*）
+ * @property l 明度（0-100）
+ * @property a 绿-红分量（典型范围-128到127）
+ * @property b 蓝-黄分量（典型范围-128到127）
+ * @see https://zh.m.wikipedia.org/wiki/CIELAB%E8%89%B2%E5%BD%A9%E7%A9%BA%E9%97%B4
+ * @example {l: 53.24, a: 80.09, b: 67.20} // 亮红色
+ */
+export type LAB = { l: number; a: number; b: number };
+
+/**
+ * CIE 1931 XYZ颜色空间类型
+ * @property x XYZ三刺激值X分量
+ * @property y XYZ三刺激值Y分量（亮度基准）
+ * @property z XYZ三刺激值Z分量
+ * @see // https://zh.m.wikipedia.org/wiki/CIE_1931%E8%89%B2%E5%BD%A9%E7%A9%BA%E9%97%B4
+ * @example {x: 95.047, y: 100.0, z: 108.883} // D65标准白点
+ */
+export type XYZ = { x: number; y: number; z: number };

package/src/color/xyz-lab.ts

@@ -0,0 +1,54 @@
+// https://stackoverflow.com/a/73998199
+
+import type { LAB, XYZ } from './types';
+
+const ref_X = 95.047;
+const ref_Y = 100.0;
+const ref_Z = 108.883;
+
+/**
+ * 将XYZ颜色转换为Lab颜色空间（CIE 1976 L*a*b*，D65白点）
+ * @param xyz XYZ颜色对象（参考值：D65白点X=95.047,Y=100,Z=108.883）
+ * @returns {LAB} Lab颜色对象：
+ *   l: 明度（0-100）
+ *   a: 绿-红分量（典型范围-128到127）
+ *   b: 蓝-黄分量（典型范围-128到127）
+ * @see https://en.wikipedia.org/wiki/CIELAB_color_space
+ * @example
+ * xyzToLab({x: 95.047, y: 100.0, z: 108.883}) // {l: 100, a: 0, b: 0}
+ */
+export function xyzToLab(xyz: XYZ): LAB {
+  const { x, y, z } = xyz;
+  const [var_X, var_Y, var_Z] = [x / ref_X, y / ref_Y, z / ref_Z].map((a) =>
+    a > 0.008856 ? a ** (1 / 3) : 7.787 * a + 16 / 116,
+  );
+
+  const l = 116 * var_Y - 16;
+  const a = 500 * (var_X - var_Y);
+  const b = 200 * (var_Y - var_Z);
+
+  return { l, a, b };
+}
+
+/**
+ * 将Lab颜色转换回XYZ颜色空间
+ * @param lab Lab颜色对象
+ * @param lab.l 明度（0-100）
+ * @param lab.a 绿-红分量（典型范围-128到127）
+ * @param lab.b 蓝-黄分量（典型范围-128到127）
+ * @returns {XYZ} XYZ颜色对象（基于D65白点）
+ * @see https://www.easyrgb.com/en/math.php
+ * @example
+ * labToXyz({l: 100, a: 0, b: 0}) // {x: 95.047, y: 100.0, z: 108.883}
+ */
+export function labToXyz(lab: LAB): XYZ {
+  const { l, a, b } = lab;
+
+  const var_Y = (l + 16) / 116;
+  const var_X = a / 500 + var_Y;
+  const var_Z = var_Y - b / 200;
+
+  const [X, Y, Z] = [var_X, var_Y, var_Z].map((n) => (n ** 3 > 0.008856 ? n ** 3 : (n - 16 / 116) / 7.787));
+
+  return { x: X * ref_X, y: Y * ref_Y, z: Z * ref_Z };
+}

package/src/color.ts

@@ -0,0 +1,19 @@
+export * from './color/contrast';
+export * from './color/distance';
+export * from './color/hex-hsl';
+export * from './color/hex-hsv';
+export * from './color/hex-hwb';
+export * from './color/hex-rgb';
+export * from './color/hsl-lighten';
+export * from './color/hsv-brighten';
+export * from './color/luminance';
+export * from './color/mix';
+export * from './color/rgb-hsl';
+export * from './color/rgb-hsv';
+export * from './color/rgb-hwb';
+export * from './color/rgb-lab';
+export * from './color/rgb-xyz';
+export * from './color/xyz-lab';
+export * from './color/rgb-whiter';
+export * from './color/types';
+export { rgbToHue } from './color/helpers';