@cloudcome/utils-core 1.1.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/{dist/color/hsl-lighten.d.ts → src/color/hsl-lighten.ts}

@@ -1,4 +1,5 @@
-import { HSL } from './types';
+import type { HSL } from './types';
+
 /**
  * 通过HSL颜色空间调整颜色亮度
  * @param hsl 原始 HSL 颜色
@@ -7,4 +8,8 @@ import { HSL } from './types';
  * @example
  * hslLighten({h: 300, s: 33, l: 44}, 0.2) // 返回亮度增加20%后的颜色
  */
-export declare function hslLighten(hsl: HSL, value: number): HSL;
+export function hslLighten(hsl: HSL, value: number): HSL {
+  const hslFinal = { ...hsl };
+  hslFinal.l = hslFinal.l * (1 + value);
+  return hslFinal;
+}

package/{dist/color/hsv-brighten.d.ts → src/color/hsv-brighten.ts}

@@ -1,4 +1,5 @@
-import { HSV } from './types';
+import type { HSV } from './types';
+
 /**
  * 通过HSV颜色空间调整颜色明度
  * @param hsv 原始HSV颜色对象
@@ -9,4 +10,8 @@ import { HSV } from './types';
  * @example
  * hsvBrighten({h: 0, s: 100, v: 50}, 0.3) // 返回{h: 0, s: 100, v: 65}
  */
-export declare function hsvBrighten(hsv: HSV, value: number): HSV;
+export function hsvBrighten(hsv: HSV, value: number): HSV {
+  const hsvFinal = { ...hsv };
+  hsvFinal.v = hsvFinal.v * (1 + value);
+  return hsvFinal;
+}

package/{dist/color/luminance.d.ts → src/color/luminance.ts}

@@ -1,4 +1,5 @@
-import { RGB } from './types';
+import type { RGB } from './types';
+
 /**
  * 计算RGB颜色的相对亮度（符合WCAG 2.1标准）
  * @param rgb RGB颜色对象（分量范围0-255）
@@ -7,4 +8,10 @@ import { RGB } from './types';
  * @example
  * luminance({r: 255, g: 255, b: 255}) // 返回1
  */
-export declare function luminance({ r, g, b }: RGB): number;
+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/{dist/color/mix.d.ts → src/color/mix.ts}

@@ -1,4 +1,5 @@
-import { HSL, HSV, RGB } from './types';
+import type { HSL, HSV, RGB } from './types';
+
 /**
  * 颜色混合函数（支持RGB/HSL/HSV色彩模型）
  * @template T 颜色类型，支持RGB、HSL或HSV对象
@@ -15,4 +16,11 @@ import { HSL, HSV, RGB } from './types';
  * // HSL混合示例
  * mix({h: 0, s: 100, l: 50}, {h: 120, s: 100, l: 50}, 0.3)
  */
-export declare function mix<T extends RGB | HSV | HSL>(a: T, b: T, weight?: number): T;
+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/{dist/color/rgb-hsv.d.ts → src/color/rgb-hsv.ts}

@@ -1,4 +1,9 @@
-import { HSV, RGB } from './types';
+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）
@@ -10,7 +15,17 @@ import { HSV, RGB } from './types';
  * @example
  * rgbToHsv({r: 255, g: 0, b: 0}) // {h: 0, s: 100, v: 100}
  */
-export declare function rgbToHsv(rgb: RGB): HSV;
+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颜色对象
@@ -22,4 +37,16 @@ export declare function rgbToHsv(rgb: RGB): HSV;
  * @example
  * hsvToRgb({h: 0, s: 100, v: 100}) // {r: 255, g: 0, b: 0}
  */
-export declare function hsvToRgb({ h, s, v }: HSV): RGB;
+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/{dist/color/rgb-lab.d.ts → src/color/rgb-lab.ts}

@@ -1,4 +1,7 @@
-import { LAB, RGB } from './types';
+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）
@@ -10,7 +13,10 @@ import { LAB, RGB } from './types';
  * @example
  * rgbToLab({r: 255, g: 0, b: 0}) // {l: 53.24, a: 80.09, b: 67.20}
  */
-export declare function rgbToLab(rgb: RGB): LAB;
+export function rgbToLab(rgb: RGB): LAB {
+  return xyzToLab(rgbToXyz(rgb));
+}
+
 /**
  * 将Lab颜色转换回RGB颜色空间
  * @param lab Lab颜色对象
@@ -22,4 +28,6 @@ export declare function rgbToLab(rgb: RGB): LAB;
  * @example
  * labToRgb({l: 53.24, a: 80.09, b: 67.20}) // {r: 255, g: 0, b: 0}
  */
-export declare function labToRgb(lab: LAB): RGB;
+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/{dist/color/types.d.ts → src/color/types.ts}

@@ -4,6 +4,7 @@
  * @example "#0f0"    // 绿色简写
  */
 export type HEX = `#${string}`;
+
 /**
  * RGB颜色空间类型
  * @property r 红色分量（0-255）
@@ -11,11 +12,8 @@ export type HEX = `#${string}`;
  * @property b 蓝色分量（0-255）
  * @example {r: 255, g: 0, b: 0} // 纯红色
  */
-export type RGB = {
-    r: number;
-    g: number;
-    b: number;
-};
+export type RGB = { r: number; g: number; b: number };
+
 /**
  * HSV/HSB颜色空间类型
  * @property h 色相（0-360度）
@@ -24,11 +22,8 @@ export type RGB = {
  * @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;
-};
+export type HSV = { h: number; s: number; v: number };
+
 /**
  * HSL颜色空间类型
  * @property h 色相（0-360度）
@@ -37,11 +32,8 @@ export type HSV = {
  * @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;
-};
+export type HSL = { h: number; s: number; l: number };
+
 /**
  * HWB颜色空间类型（W3C标准）
  * @property h 色相（0-360度）
@@ -50,11 +42,8 @@ export type HSL = {
  * @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;
-};
+export type HWB = { h: number; w: number; b: number };
+
 /**
  * CIE LAB颜色空间类型（L*a*b*）
  * @property l 明度（0-100）
@@ -63,11 +52,8 @@ export type HWB = {
  * @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;
-};
+export type LAB = { l: number; a: number; b: number };
+
 /**
  * CIE 1931 XYZ颜色空间类型
  * @property x XYZ三刺激值X分量
@@ -76,8 +62,4 @@ export type LAB = {
  * @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;
-};
+export type XYZ = { x: number; y: number; z: number };

package/{dist/color/xyz-lab.d.ts → src/color/xyz-lab.ts}

@@ -1,4 +1,11 @@
-import { LAB, XYZ } from './types';
+// 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）
@@ -10,7 +17,19 @@ import { LAB, XYZ } from './types';
  * @example
  * xyzToLab({x: 95.047, y: 100.0, z: 108.883}) // {l: 100, a: 0, b: 0}
  */
-export declare function xyzToLab(xyz: XYZ): LAB;
+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颜色对象
@@ -22,4 +41,14 @@ export declare function xyzToLab(xyz: XYZ): LAB;
  * @example
  * labToXyz({l: 100, a: 0, b: 0}) // {x: 95.047, y: 100.0, z: 108.883}
  */
-export declare function labToXyz(lab: LAB): XYZ;
+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 };
+}