@cloudcome/utils-core 1.19.1 → 1.20.0

package/dist/color.mjs

@@ -1,250 +1,533 @@
+//#region src/color/luminance.ts
+/**
+* 计算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
+*/
 function luminance({ r, g, b }) {
-  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;
+	const a = [
+		r,
+		g,
+		b
+	].map((v) => {
+		const vFinal = v / 255;
+		return vFinal <= .03928 ? vFinal / 12.92 : ((vFinal + .055) / 1.055) ** 2.4;
+	});
+	return a[0] * .2126 + a[1] * .7152 + a[2] * .0722;
 }
+//#endregion
+//#region src/color/contrast.ts
+/**
+* 计算两个颜色之间的对比度比率（符合WCAG 2.1标准）
+* @param rgb1 第一个RGB颜色对象（分量范围0-255）
+* @param rgb2 第二个RGB颜色对象（分量范围0-255）
+* @returns {number} 对比度比率，范围1-21（1:1 到 21:1）
+* @example
+* contrast({r: 0, g: 0, b: 0}, {r: 255, g: 255, b: 255}) // 返回21
+*/
 function contrast(rgb1, rgb2) {
-  const lum1 = luminance(rgb1);
-  const lum2 = luminance(rgb2);
-  const brightest = Math.max(lum1, lum2);
-  const darkest = Math.min(lum1, lum2);
-  return (brightest + 0.05) / (darkest + 0.05);
+	const lum1 = luminance(rgb1);
+	const lum2 = luminance(rgb2);
+	const brightest = Math.max(lum1, lum2);
+	const darkest = Math.min(lum1, lum2);
+	return (brightest + .05) / (darkest + .05);
 }
+//#endregion
+//#region src/color/distance.ts
+/**
+* 计算两个颜色之间的距离（距离越小相似度越高），值范围 [0, 1]
+* @param {LAB} labA
+* @param {LAB} labB
+* @returns {number}
+*/
 function distance(labA, labB) {
-  const deltaL = labA.l - labB.l;
-  const deltaA = labA.a - labB.a;
-  const deltaB = labA.b - labB.b;
-  const c1 = Math.sqrt(labA.a * labA.a + labA.b * labA.b);
-  const c2 = Math.sqrt(labB.a * labB.a + labB.b * labB.b);
-  const deltaC = c1 - c2;
-  let deltaH = deltaA * deltaA + deltaB * deltaB - deltaC * deltaC;
-  deltaH = deltaH < 0 ? 0 : Math.sqrt(deltaH);
-  const sc = 1 + 0.045 * c1;
-  const sh = 1 + 0.015 * c1;
-  const deltaLKlsl = deltaL / 1;
-  const deltaCkcsc = deltaC / sc;
-  const deltaHkhsh = deltaH / sh;
-  const i = deltaLKlsl * deltaLKlsl + deltaCkcsc * deltaCkcsc + deltaHkhsh * deltaHkhsh;
-  return (i < 0 ? 0 : Math.sqrt(i)) / 100;
+	const deltaL = labA.l - labB.l;
+	const deltaA = labA.a - labB.a;
+	const deltaB = labA.b - labB.b;
+	const c1 = Math.sqrt(labA.a * labA.a + labA.b * labA.b);
+	const deltaC = c1 - Math.sqrt(labB.a * labB.a + labB.b * labB.b);
+	let deltaH = deltaA * deltaA + deltaB * deltaB - deltaC * deltaC;
+	deltaH = deltaH < 0 ? 0 : Math.sqrt(deltaH);
+	const sc = 1 + .045 * c1;
+	const sh = 1 + .015 * c1;
+	const deltaLKlsl = deltaL / 1;
+	const deltaCkcsc = deltaC / sc;
+	const deltaHkhsh = deltaH / sh;
+	const i = deltaLKlsl * deltaLKlsl + deltaCkcsc * deltaCkcsc + deltaHkhsh * deltaHkhsh;
+	return (i < 0 ? 0 : Math.sqrt(i)) / 100;
 }
+//#endregion
+//#region src/color/helpers.ts
+var { min: min$2, max: max$2 } = Math;
+function rgbToHue({ r, g, b }) {
+	r /= 255;
+	g /= 255;
+	b /= 255;
+	const rgbMax = max$2(r, g, b);
+	const rgbMin = min$2(r, g, b);
+	const rgbDiff = rgbMax - rgbMin;
+	const h = rgbDiff === 0 ? 0 : rgbDiff && rgbMax === r ? (g - b) / rgbDiff : rgbMax === g ? 2 + (b - r) / rgbDiff : 4 + (r - g) / rgbDiff;
+	return [
+		60 * (h < 0 ? h + 6 : h),
+		rgbMax,
+		rgbMin,
+		rgbDiff
+	];
+}
+//#endregion
+//#region src/color/hex-rgb.ts
+/**
+* 将HEX颜色字符串转换为RGB颜色对象
+* @param hex HEX颜色字符串，支持3位或6位格式（例如#f00或#ff0000）
+* @returns {RGB} 对应的RGB颜色对象
+* @throws {SyntaxError} 当颜色格式不符合规范时抛出
+* @example
+* hexToRgb('#f00') // returns {r: 255, g: 0, b: 0}
+*/
 function hexToRgb(hex) {
-  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)
-  };
+	const result = (hex.length === 4 ? /^#(.)(.)(.)$/ : /^#(.{2})(.{2})(.{2})$/).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) {
-  return Math.round(n).toString(16).padStart(2, "0");
+	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'
+*/
 function rgbToHex(rgb) {
-  return `#${to16(rgb.r)}${to16(rgb.g)}${to16(rgb.b)}`;
+	return `#${to16(rgb.r)}${to16(rgb.g)}${to16(rgb.b)}`;
 }
-const { min: min$2, max: max$2 } = Math;
-function rgbToHue({ r, g, b }) {
-  r /= 255;
-  g /= 255;
-  b /= 255;
-  const rgbMax = max$2(r, g, b);
-  const rgbMin = min$2(r, g, b);
-  const rgbDiff = rgbMax - rgbMin;
-  const h = rgbDiff === 0 ? 0 : rgbDiff && rgbMax === r ? (g - b) / rgbDiff : rgbMax === g ? 2 + (b - r) / rgbDiff : 4 + (r - g) / rgbDiff;
-  return [60 * (h < 0 ? h + 6 : h), rgbMax, rgbMin, rgbDiff];
-}
-const { min: min$1, max: max$1 } = Math;
+//#endregion
+//#region src/color/rgb-hsl.ts
+var { min: min$1, max: max$1 } = 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}
+*/
 function rgbToHsl(rgb) {
-  const [hue, max2, min2, diff] = rgbToHue(rgb);
-  const l = (2 * max2 - diff) / 2;
-  const s = min2 === max2 ? 0 : l < 0.5 ? (max2 - min2) / (max2 + min2) : (max2 - min2) / (2 - max2 - min2);
-  return {
-    h: hue,
-    s: s * 100,
-    l: l * 100
-  };
+	const [hue, max, min, diff] = rgbToHue(rgb);
+	const l = (2 * max - diff) / 2;
+	return {
+		h: hue,
+		s: (min === max ? 0 : l < .5 ? (max - min) / (max + min) : (max - min) / (2 - max - min)) * 100,
+		l: l * 100
+	};
 }
+/**
+* 将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}
+*/
 function hslToRgb({ h, s, l }) {
-  s /= 100;
-  l /= 100;
-  const a = s * min$1(l, 1 - l);
-  const k = (n) => (n + h / 30) % 12;
-  const f = (n) => l - a * max$1(-1, min$1(k(n) - 3, min$1(9 - k(n), 1)));
-  return {
-    r: 255 * f(0),
-    g: 255 * f(8),
-    b: 255 * f(4)
-  };
+	s /= 100;
+	l /= 100;
+	const a = s * min$1(l, 1 - l);
+	const k = (n) => (n + h / 30) % 12;
+	const f = (n) => l - a * max$1(-1, min$1(k(n) - 3, min$1(9 - k(n), 1)));
+	return {
+		r: 255 * f(0),
+		g: 255 * f(8),
+		b: 255 * f(4)
+	};
 }
+//#endregion
+//#region src/color/hex-hsl.ts
 function hslToHex(hsl) {
-  return rgbToHex(hslToRgb(hsl));
+	return rgbToHex(hslToRgb(hsl));
 }
 function hexToHsl(hex) {
-  return rgbToHsl(hexToRgb(hex));
+	return rgbToHsl(hexToRgb(hex));
 }
-const { min, max } = Math;
+//#endregion
+//#region src/color/rgb-hsv.ts
+var { min, max } = Math;
+/**
+* 将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}
+*/
 function rgbToHsv(rgb) {
-  const [hue, max2, min2, diff] = rgbToHue(rgb);
-  return {
-    h: hue,
-    s: max2 && diff / max2 * 100,
-    v: max2 * 100
-  };
+	const [hue, max, _min, diff] = rgbToHue(rgb);
+	return {
+		h: hue,
+		s: max && diff / max * 100,
+		v: max * 100
+	};
 }
+/**
+* 将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}
+*/
 function hsvToRgb({ h, s, v }) {
-  s /= 100;
-  v /= 100;
-  const k = (n) => (n + h / 60) % 6;
-  const f = (n) => 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)
-  };
+	s /= 100;
+	v /= 100;
+	const k = (n) => (n + h / 60) % 6;
+	const f = (n) => 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)
+	};
 }
+//#endregion
+//#region src/color/hex-hsv.ts
+/**
+* 将HEX颜色转换为HSV颜色空间
+* @param hex HEX颜色字符串（支持3位或6位格式）
+* @returns {HSV} HSV颜色对象，包含：
+*   h: 色相（0-360度）
+*   s: 饱和度（0-100%）
+*   v: 明度（0-100%）
+* @example
+* hexToHsv('#ff0000') // returns {h: 0, s: 100, v: 100}
+*/
 function hexToHsv(hex) {
-  return rgbToHsv(hexToRgb(hex));
+	return rgbToHsv(hexToRgb(hex));
 }
+/**
+* 将HSV颜色转换回HEX字符串
+* @param hsv HSV颜色对象
+* @returns {HEX} 6位HEX颜色字符串（带#前缀）
+* @example
+* hsvToHex({h: 0, s: 100, v: 100}) // returns '#ff0000'
+*/
 function hsvToHex(hsv) {
-  return rgbToHex(hsvToRgb(hsv));
+	return rgbToHex(hsvToRgb(hsv));
 }
+//#endregion
+//#region src/color/rgb-hwb.ts
+/**
+* 将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}
+*/
 function rgbToHwb(rgb) {
-  const [hue, max2, min2, diff] = rgbToHue(rgb);
-  return {
-    h: hue,
-    w: min2 * 100,
-    b: (1 - max2) * 100
-  };
+	const [hue, max, min, _diff] = rgbToHue(rgb);
+	return {
+		h: hue,
+		w: min * 100,
+		b: (1 - max) * 100
+	};
 }
+/**
+* 将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}
+*/
 function hwbToRgb({ h, w: white, b: black }) {
-  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) => (n / 255 * (1 - white - black) + white) * 255;
-  return {
-    r: f(r),
-    g: f(g),
-    b: f(b)
-  };
+	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) => (n / 255 * (1 - white - black) + white) * 255;
+	return {
+		r: f(r),
+		g: f(g),
+		b: f(b)
+	};
 }
+//#endregion
+//#region src/color/hex-hwb.ts
+/**
+* 将HWB颜色转换为HEX字符串
+* @param hwb HWB颜色对象
+* @param hwb.h 色相（0-360度）
+* @param hwb.w 白度（0-100%）
+* @param hwb.b 黑度（0-100%）
+* @returns {HEX} 6位HEX颜色字符串（带#前缀）
+* @example
+* hwbToHex({h: 0, w: 0, b: 0}) // returns '#ff0000'
+*/
 function hwbToHex(hwb) {
-  return rgbToHex(hwbToRgb(hwb));
+	return rgbToHex(hwbToRgb(hwb));
 }
+/**
+* 将HEX颜色转换为HWB颜色空间
+* @param hex HEX颜色字符串（支持3位或6位格式）
+* @returns {HWB} HWB颜色对象，包含：
+*   h: 色相（0-360度）
+*   w: 白度（0-100%）
+*   b: 黑度（0-100%）
+* @example
+* hexToHwb('#ff0000') // returns {h: 0, w: 0, b: 0}
+*/
 function hexToHwb(hex) {
-  return rgbToHwb(hexToRgb(hex));
+	return rgbToHwb(hexToRgb(hex));
 }
+//#endregion
+//#region src/color/hsl-lighten.ts
+/**
+* 通过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%后的颜色
+*/
 function hslLighten(hsl, value) {
-  const hslFinal = { ...hsl };
-  hslFinal.l = hslFinal.l * (1 + value);
-  return hslFinal;
+	const hslFinal = { ...hsl };
+	hslFinal.l = hslFinal.l * (1 + value);
+	return hslFinal;
 }
+//#endregion
+//#region src/color/hsv-brighten.ts
+/**
+* 通过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}
+*/
 function hsvBrighten(hsv, value) {
-  const hsvFinal = { ...hsv };
-  hsvFinal.v = hsvFinal.v * (1 + value);
-  return hsvFinal;
+	const hsvFinal = { ...hsv };
+	hsvFinal.v = hsvFinal.v * (1 + value);
+	return hsvFinal;
 }
-function mix(a, b, weight = 0.5) {
-  return Object.keys(a).reduce((acc, key) => {
-    acc[key] = (b[key] - a[key]) * weight + a[key];
-    return acc;
-  }, {});
+//#endregion
+//#region src/color/mix.ts
+/**
+* 颜色混合函数（支持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)
+*/
+function mix(a, b, weight = .5) {
+	return Object.keys(a).reduce((acc, key) => {
+		acc[key] = (b[key] - a[key]) * weight + a[key];
+		return acc;
+	}, {});
 }
+//#endregion
+//#region src/color/rgb-xyz.ts
+/**
+* 将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}
+*/
 function rgbToXyz(rgb) {
-  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
-  };
+	const { r, g, b } = rgb;
+	const [var_R, var_G, var_B] = [
+		r,
+		g,
+		b
+	].map((x) => x / 255).map((x) => x > .04045 ? ((x + .055) / 1.055) ** 2.4 : x / 12.92).map((x) => x * 100);
+	return {
+		x: var_R * .4124 + var_G * .3576 + var_B * .1805,
+		y: var_R * .2126 + var_G * .7152 + var_B * .0722,
+		z: var_R * .0193 + var_G * .1192 + var_B * .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}
+*/
 function xyzToRgb(xyz) {
-  const { x, y, z } = xyz;
-  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 > 31308e-7 ? 1.055 * n ** (1 / 2.4) - 0.055 : 12.92 * n).map((n) => n * 255);
-  return {
-    r,
-    g,
-    b
-  };
-}
-const ref_X = 95.047;
-const ref_Y = 100;
-const ref_Z = 108.883;
+	const { x, y, z } = xyz;
+	const var_X = x / 100;
+	const var_Y = y / 100;
+	const var_Z = z / 100;
+	const [r, g, b] = [
+		var_X * 3.2406 + var_Y * -1.5372 + var_Z * -.4986,
+		var_X * -.9689 + var_Y * 1.8758 + var_Z * .0415,
+		var_X * .0557 + var_Y * -.204 + var_Z * 1.057
+	].map((n) => n > .0031308 ? 1.055 * n ** (1 / 2.4) - .055 : 12.92 * n).map((n) => n * 255);
+	return {
+		r,
+		g,
+		b
+	};
+}
+//#endregion
+//#region src/color/xyz-lab.ts
+var ref_X = 95.047;
+var ref_Y = 100;
+var 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}
+*/
 function xyzToLab(xyz) {
-  const { x, y, z } = xyz;
-  const [var_X, var_Y, var_Z] = [x / ref_X, y / ref_Y, z / ref_Z].map(
-    (a2) => a2 > 8856e-6 ? a2 ** (1 / 3) : 7.787 * a2 + 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 };
+	const { x, y, z } = xyz;
+	const [var_X, var_Y, var_Z] = [
+		x / ref_X,
+		y / ref_Y,
+		z / ref_Z
+	].map((a) => a > .008856 ? a ** (1 / 3) : 7.787 * a + 16 / 116);
+	return {
+		l: 116 * var_Y - 16,
+		a: 500 * (var_X - var_Y),
+		b: 200 * (var_Y - var_Z)
+	};
 }
+/**
+* 将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}
+*/
 function labToXyz(lab) {
-  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 > 8856e-6 ? n ** 3 : (n - 16 / 116) / 7.787);
-  return { x: X * ref_X, y: Y * ref_Y, z: Z * ref_Z };
+	const { l, a, b } = lab;
+	const var_Y = (l + 16) / 116;
+	const [X, Y, Z] = [
+		a / 500 + var_Y,
+		var_Y,
+		var_Y - b / 200
+	].map((n) => n ** 3 > .008856 ? n ** 3 : (n - 16 / 116) / 7.787);
+	return {
+		x: X * ref_X,
+		y: Y * ref_Y,
+		z: Z * ref_Z
+	};
 }
+//#endregion
+//#region src/color/rgb-lab.ts
+/**
+* 将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}
+*/
 function rgbToLab(rgb) {
-  return xyzToLab(rgbToXyz(rgb));
+	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}
+*/
 function labToRgb(lab) {
-  return xyzToRgb(labToXyz(lab));
+	return xyzToRgb(labToXyz(lab));
 }
-const { abs } = Math;
-const whiteRGB = { r: 0, g: 0, b: 0 };
-const blackRGB = { r: 255, g: 255, b: 255 };
-function rgbWhiter(rgb, value) {
-  const rgb2 = value > 0 ? whiteRGB : blackRGB;
-  return mix(rgb, rgb2, abs(value));
-}
-export {
-  contrast,
-  distance,
-  hexToHsl,
-  hexToHsv,
-  hexToHwb,
-  hexToRgb,
-  hslLighten,
-  hslToHex,
-  hslToRgb,
-  hsvBrighten,
-  hsvToHex,
-  hsvToRgb,
-  hwbToHex,
-  hwbToRgb,
-  labToRgb,
-  labToXyz,
-  luminance,
-  mix,
-  rgbToHex,
-  rgbToHsl,
-  rgbToHsv,
-  rgbToHue,
-  rgbToHwb,
-  rgbToLab,
-  rgbToXyz,
-  rgbWhiter,
-  xyzToLab,
-  xyzToRgb
+//#endregion
+//#region src/color/rgb-whiter.ts
+var { abs } = Math;
+var whiteRGB = {
+	r: 0,
+	g: 0,
+	b: 0
+};
+var blackRGB = {
+	r: 255,
+	g: 255,
+	b: 255
 };
-//# sourceMappingURL=color.mjs.map
+/**
+* 通过混合颜色调整明暗度
+* @param rgb 原始RGB颜色对象
+* @param value 调整强度（-1到1之间）：
+*   - 正值时与黑色混合（增加暗度）
+*   - 负值时与白色混合（增加亮度）
+* @returns {RGB} 调整后的RGB颜色对象
+* @example
+* rgbDarken({r: 100, g: 150, b: 200}, 0.2) // 变暗20%
+*/
+function rgbWhiter(rgb, value) {
+	return mix(rgb, value > 0 ? whiteRGB : blackRGB, abs(value));
+}
+//#endregion
+export { contrast, distance, hexToHsl, hexToHsv, hexToHwb, hexToRgb, hslLighten, hslToHex, hslToRgb, hsvBrighten, hsvToHex, hsvToRgb, hwbToHex, hwbToRgb, labToRgb, labToXyz, luminance, mix, rgbToHex, rgbToHsl, rgbToHsv, rgbToHue, rgbToHwb, rgbToLab, rgbToXyz, rgbWhiter, xyzToLab, xyzToRgb };
+
+//# sourceMappingURL=color.mjs.map