toolbox-x 1.0.0

package/dist/convert-BrzlG-m_.cjs

@@ -0,0 +1,475 @@
+/**
+ * Copyright 2026 - present Nazmul Hassan
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+const require_primitives = require('./primitives-B26uZolQ.cjs');
+const require_guards = require('./guards-C8gkvIHb.cjs');
+
+//#region src/colors/utils.ts
+/**
+* * Extracts numbers from a color string like `rgb(66, 103, 69)` or `hsl(120, 42.86%, 41.18%)`.
+* * Converts percentage values to decimal (e.g., `42.86%` → `42.86`).
+*
+* @param color The color string in RGB or HSL format.
+* @returns A tuple of 3 extracted numbers. `[number, number, number]`
+*
+* @remarks If the input color is not in `HSL` or `RGB` format, it will return `[0, 0, 0]`
+*/
+function extractSolidColorValues(color) {
+	if (require_guards.isHSL(color) || require_guards.isRGB(color)) return (color?.trim()?.match(/[\d.]+%?/g) || [])?.map((value) => parseFloat(value));
+	return [
+		0,
+		0,
+		0
+	];
+}
+/**
+* * Extracts numbers from a color string like `rgba(66, 103, 69, 0.6)` or `hsla(120, 42.86%, 41.18%, 0.9)`.
+* * Converts percentage values to decimal (e.g., `42.86%` → `42.86`).
+*
+* @param color The color string in RGBA or HSLA format.
+* @returns A tuple of 4 extracted numbers. `[number, number, number, number]`
+*
+* @remarks If the input color is not in `HSLA` or `RGBA` format, it will return `[0, 0, 0, 0]`
+*/
+function extractAlphaColorValues(color) {
+	if (require_guards.isHSLA(color) || require_guards.isRGBA(color)) return (color?.trim()?.match(/[\d.]+%?/g) || [])?.map((value) => parseFloat(value));
+	return [
+		0,
+		0,
+		0,
+		0
+	];
+}
+/**
+* * Converts percentage (0-100) to a 2-digit hex string.
+*
+* @param percent - The percentage (0-100) value.
+* @returns A 2-digit hex string representing the percentage (0-100) value.
+*
+* @remarks
+* - This function ensures that the percentage value is clamped between 0 and 100, converts it to a value between 0 and 255, and then formats it as a 2-digit hexadecimal string.
+* - The resulting hex string is in uppercase for consistency with common hex color formats.
+*
+* @example
+* percentToHex(0);    // Returns "00"
+* percentToHex(50);   // Returns "7F"
+* percentToHex(100);  // Returns "FF"
+* percentToHex(150);  // Returns "FF" (ts compiler error and clamped to 100)
+* percentToHex(-20);  // Returns "00" (ts compiler error and clamped to 0)
+*/
+function percentToHex(percent) {
+	return Math.round(Math.min(100, Math.max(0, percent)) / 100 * 255).toString(16).padStart(2, "0").toUpperCase();
+}
+/**
+* * Applies an opacity value to a hex color string.
+*
+* @param color - The hex color string in the format `#RRGGBB` or `#RRGGBBAA`.
+* @param opacity - The opacity value as a percentage (0-100) or a 2-digit hex string.
+* @returns The hex color string with the applied opacity in `#RRGGBBAA` format.
+*/
+function applyOpacityToHex(color, opacity) {
+	if (require_guards.isHex6(color) || require_guards.isHex8(color)) {
+		const upperColor = color.toUpperCase();
+		if (require_primitives.isNumber(opacity)) return require_guards._applyOpacity(upperColor, percentToHex(opacity));
+		else if (require_primitives.isNonEmptyString(opacity) && /^[0-9A-Fa-f]{2}$/.test(opacity)) return require_guards._applyOpacity(upperColor, opacity.toUpperCase());
+		else return require_guards._applyOpacity(upperColor, percentToHex(100));
+	} else throw new TypeError("Invalid color value!", { cause: "Value must be a hex color string in the format #RRGGBB or #RRGGBBAA." });
+}
+
+//#endregion
+//#region src/colors/convert.ts
+/**
+* * Converts HSL to RGB color format.
+*
+* @param h - The hue component of the HSL color, in degrees (0 to 360).
+* @param s - The saturation component of the HSL color, as a percentage (0 to 100).
+* @param l - The lightness component of the HSL color, as a percentage (0 to 100).
+* @returns A string representing the color in RGB format (e.g., `rgb(255, 0, 0)`).
+*/
+const convertHslToRgb = (h, s, l) => {
+	s /= 100;
+	l /= 100;
+	const c = (1 - Math.abs(2 * l - 1)) * s;
+	const x = c * (1 - Math.abs(h / 60 % 2 - 1));
+	const m = l - c / 2;
+	let r = 0, g = 0, b = 0;
+	if (h >= 0 && h < 60) [r, g] = [c, x];
+	else if (h >= 60 && h < 120) [r, g] = [x, c];
+	else if (h >= 120 && h < 180) [g, b] = [c, x];
+	else if (h >= 180 && h < 240) [g, b] = [x, c];
+	else if (h >= 240 && h < 300) [r, b] = [x, c];
+	else if (h >= 300 && h < 360) [r, b] = [c, x];
+	r = Math.round((r + m) * 255);
+	g = Math.round((g + m) * 255);
+	b = Math.round((b + m) * 255);
+	return `rgb(${r}, ${g}, ${b})`;
+};
+/**
+* * Converts RGB to HSL color format.
+*
+* @param r - The red component of the RGB color, in the range 0 to 255.
+* @param g - The green component of the RGB color, in the range 0 to 255.
+* @param b - The blue component of the RGB color, in the range 0 to 255.
+* @returns A string representing the color in HSL format (e.g., `hsl(0, 100%, 50%)`).
+*/
+const convertRgbToHsl = (r, g, b) => {
+	r /= 255;
+	g /= 255;
+	b /= 255;
+	const max = Math.max(r, g, b);
+	const min = Math.min(r, g, b);
+	let h = 0, s = 0;
+	const l = (max + min) / 2;
+	if (max !== min) {
+		const diff = max - min;
+		s = l > .5 ? diff / (2 - max - min) : diff / (max + min);
+		switch (max) {
+			case r:
+				h = (g - b) / diff + (g < b ? 6 : 0);
+				break;
+			case g:
+				h = (b - r) / diff + 2;
+				break;
+			case b:
+				h = (r - g) / diff + 4;
+				break;
+		}
+		h *= 60;
+	}
+	return `hsl(${Math.round(h)}, ${Number((s * 100).toFixed(2))}%, ${Number((l * 100).toFixed(2))}%)`;
+};
+/**
+* * Converts HSL to Hex color format.
+*
+* @param h - The hue component of the HSL color, in degrees (0 to 360).
+* @param s - The saturation component of the HSL color, as a percentage (0 to 100).
+* @param l - The lightness component of the HSL color, as a percentage (0 to 100).
+* @returns A string representing the color in Hex format (e.g., `#FF0000`).
+*/
+const convertHslToHex = (h, s, l) => {
+	const rgb = convertHslToRgb(h, s, l).match(/\d+/g).map(Number);
+	return convertRgbToHex(rgb[0], rgb[1], rgb[2]);
+};
+/**
+* * Converts Hex to HSL color format.
+*
+* @param hex - A string representing the color in Hex format (e.g., `#FF0000`).
+* @returns A string representing the color in HSL format (e.g., `hsl(0, 100%, 50%)`).
+*/
+const convertHexToHsl = (hex) => {
+	let newHex = hex?.trim()?.replace("#", "");
+	if (newHex?.length === 3) newHex = newHex?.split("")?.map((char) => char + char)?.join("");
+	return convertRgbToHsl(parseInt(newHex.slice(0, 2), 16), parseInt(newHex.slice(2, 4), 16), parseInt(newHex.slice(4, 6), 16));
+};
+/**
+* * Converts RGB to Hex color format.
+*
+* @param r - The red component of the RGB color, in the range 0 to 255.
+* @param g - The green component of the RGB color, in the range 0 to 255.
+* @param b - The blue component of the RGB color, in the range 0 to 255.
+* @returns A string representing the color in Hex format (e.g., `#FF0000`).
+*/
+const convertRgbToHex = (r, g, b) => {
+	return `#${[
+		r,
+		g,
+		b
+	]?.map((v) => v.toString(16).padStart(2, "0"))?.join("")?.toUpperCase()}`;
+};
+/**
+* * Converts Hex to RGB color format.
+*
+* @param hex - A string representing the color in Hex format (e.g., `#FF0000`).
+* @returns A string representing the color in RGB format (e.g., `rgb(255, 0, 0)`).
+*/
+const convertHexToRgb = (hex) => {
+	let newHex = hex?.trim()?.replace("#", "");
+	if (newHex?.length === 3) newHex = newHex?.split("")?.map((char) => char + char)?.join("");
+	return `rgb(${parseInt(newHex.slice(0, 2), 16)}, ${parseInt(newHex.slice(2, 4), 16)}, ${parseInt(newHex.slice(4, 6), 16)})`;
+};
+/**
+* * Converts RGB to RGBA format, adding alpha (opacity).
+*
+* @param r - The red component of the RGB color, in the range 0 to 255.
+* @param g - The green component of the RGB color, in the range 0 to 255.
+* @param b - The blue component of the RGB color, in the range 0 to 255.
+* @param a - The alpha (opacity) value, in the range 0 to 1.
+* @returns A string representing the color in RGBA format (e.g., `rgba(255, 0, 0, 0.5)`).
+*/
+const convertRgbToRgba = (r, g, b, a = 1) => {
+	let newAlpha = a;
+	if (!require_guards._isValidAlpha(a)) {
+		newAlpha = 1;
+		console.warn(`Alpha value must be between 0-1, ${a} converted to 1!`);
+	}
+	return `rgba(${r}, ${g}, ${b}, ${parseFloat(newAlpha.toFixed(1))})`;
+};
+/**
+* * Converts RGBA to Hex format, including alpha channel as part of Hex8.
+*
+* @param r - The red component of the RGB color, in the range 0 to 255.
+* @param g - The green component of the RGB color, in the range 0 to 255.
+* @param b - The blue component of the RGB color, in the range 0 to 255.
+* @param a - The alpha (opacity) value, in the range 0 to 1.
+* @returns A string representing the color in Hex8 format (e.g., `#FF000080`).
+*/
+const convertRgbaToHex8 = (r, g, b, a = 1) => {
+	let newAlpha = a;
+	if (!require_guards._isValidAlpha(a)) {
+		newAlpha = 1;
+		console.warn(`Alpha value must be between 0-1, ${a} converted to 1!`);
+	}
+	const alphaHex = percentToHex(Math.round(newAlpha * 100));
+	return `${convertRgbToHex(r, g, b)}${alphaHex}`;
+};
+/**
+* * Converts HSLA to RGBA color format, including alpha channel.
+*
+* @param h - The hue component of the HSL color, in degrees (0 to 360).
+* @param s - The saturation component of the HSL color, as a percentage (0 to 100).
+* @param l - The lightness component of the HSL color, as a percentage (0 to 100).
+* @param a - The alpha (opacity) value, in the range 0 to 1.
+* @returns A string representing the color in RGBA format (e.g., `rgba(255, 0, 0, 0.5)`).
+*/
+const convertHslaToRgba = (h, s, l, a = 1) => {
+	let newAlpha = a;
+	if (!require_guards._isValidAlpha(a)) {
+		newAlpha = 1;
+		console.warn(`Alpha value must be between 0-1, ${a} converted to 1!`);
+	}
+	const [r, g, b] = extractSolidColorValues(convertHslToRgb(h, s, l));
+	return convertRgbToRgba(r, g, b, parseFloat(newAlpha.toFixed(1)));
+};
+/**
+* * Converts RGBA to HSLA color format, including alpha channel.
+*
+* @param r - The red component of the RGB color, in the range 0 to 255.
+* @param g - The green component of the RGB color, in the range 0 to 255.
+* @param b - The blue component of the RGB color, in the range 0 to 255.
+* @param a - The alpha (opacity) value, in the range 0 to 1.
+* @returns A string representing the color in HSLA format (e.g., `hsla(0, 100%, 50%, 0.5)`).
+*/
+const convertRgbaToHsla = (r, g, b, a = 1) => {
+	let newAlpha = a;
+	if (!require_guards._isValidAlpha(a)) {
+		newAlpha = 1;
+		console.warn(`Alpha value must be between 0-1, ${a} converted to 1!`);
+	}
+	const [h, s, l] = extractSolidColorValues(convertRgbToHsl(r, g, b));
+	return `hsla(${h}, ${s}%, ${l}%, ${parseFloat(newAlpha.toFixed(1))})`;
+};
+/**
+* * Converts Hex8 to RGBA color format, including alpha channel.
+* - `Special Note:` Cast the parameter to `Hex8` before converting to `RGBA`.
+* @example convertHex8ToRgba('#FFF122DE' as Hex8)
+*
+* @param hex8 - A string representing the color in Hex8 format (e.g., `#FF000080`).
+* @returns A string representing the color in RGBA format (e.g., `rgba(255, 0, 0, 0.5)`).
+*/
+const convertHex8ToRgba = (hex8) => {
+	const hex = hex8?.trim()?.replace("#", "");
+	const r = parseInt(hex.slice(0, 2), 16);
+	const g = parseInt(hex.slice(2, 4), 16);
+	const b = parseInt(hex.slice(4, 6), 16);
+	const a = parseInt(hex.slice(6, 8), 16) / 255;
+	return `rgba(${r}, ${g}, ${b}, ${parseFloat(a.toFixed(1))})`;
+};
+/**
+* * Converts HSLA to Hex8 color format, including alpha channel.
+*
+* @param h - The hue component of the HSL color, in degrees (0 to 360).
+* @param s - The saturation component of the HSL color, as a percentage (0 to 100).
+* @param l - The lightness component of the HSL color, as a percentage (0 to 100).
+* @param a - The alpha (opacity) value, in the range 0 to 1.
+* @returns A string representing the color in Hex8 format (e.g., `#658789DF`).
+*/
+const convertHslaToHex8 = (h, s, l, a = 1) => {
+	let newAlpha = a;
+	if (!require_guards._isValidAlpha(a)) {
+		newAlpha = 1;
+		console.warn(`Alpha value must be between 0-1, ${a} converted to 1!`);
+	}
+	const alphaHex = percentToHex(Math.round(newAlpha * 100));
+	return `${convertHslToHex(h, s, l)}${alphaHex}`;
+};
+/**
+* * Converts Hex8 to HSLA color format.
+* - `Special Note:` Cast the parameter to `Hex8` before converting to `HSLA`.
+* @example convertHex8ToHsla('#FFF122DE' as Hex8)
+*
+* @param hex - A string representing the color in Hex format (e.g., `#FF0000DE`).
+* @returns A string representing the color in HSLA format..
+*/
+const convertHex8ToHsla = (hex8) => {
+	return convertRgbaToHsla(...extractAlphaColorValues(convertHex8ToRgba(hex8)));
+};
+/**
+* * Converts a color from `Hex`, `RGB`, or `HSL` format to its equivalent representations.
+*
+* @param color The color string in `Hex`, `RGB`, or `HSL` format.
+* @returns The converted color representations excluding the input format.
+* @throws If the color format is unrecognized throws `Error`.
+*/
+function convertColorCode(color) {
+	const trimmedColor = color?.trim();
+	if (require_guards.isHex6(trimmedColor)) return {
+		rgb: convertHexToRgb(trimmedColor),
+		hsl: convertHexToHsl(trimmedColor)
+	};
+	if (require_guards.isRGB(trimmedColor)) {
+		const rgbValues = extractSolidColorValues(trimmedColor);
+		return {
+			hex: convertRgbToHex(...rgbValues),
+			hsl: convertRgbToHsl(...rgbValues)
+		};
+	}
+	if (require_guards.isHSL(trimmedColor)) {
+		const hslValues = extractSolidColorValues(trimmedColor);
+		return {
+			hex: convertHslToHex(...hslValues),
+			rgb: convertHslToRgb(...hslValues)
+		};
+	}
+	if (require_guards.isHex8(trimmedColor)) return {
+		rgba: convertHex8ToRgba(trimmedColor),
+		hsla: convertHex8ToHsla(trimmedColor)
+	};
+	if (require_guards.isRGBA(trimmedColor)) {
+		const rgbaValues = extractAlphaColorValues(trimmedColor);
+		return {
+			hex8: convertRgbaToHex8(...rgbaValues),
+			hsla: convertRgbaToHsla(...rgbaValues)
+		};
+	}
+	if (require_guards.isHSLA(trimmedColor)) {
+		const hslaValues = extractAlphaColorValues(trimmedColor);
+		return {
+			hex8: convertHslaToHex8(...hslaValues),
+			rgba: convertHslaToRgba(...hslaValues)
+		};
+	}
+	throw new TypeError(`${color} is not a valid color!`, { cause: "Unrecognized Color Format" });
+}
+
+//#endregion
+Object.defineProperty(exports, 'applyOpacityToHex', {
+  enumerable: true,
+  get: function () {
+    return applyOpacityToHex;
+  }
+});
+Object.defineProperty(exports, 'convertColorCode', {
+  enumerable: true,
+  get: function () {
+    return convertColorCode;
+  }
+});
+Object.defineProperty(exports, 'convertHex8ToHsla', {
+  enumerable: true,
+  get: function () {
+    return convertHex8ToHsla;
+  }
+});
+Object.defineProperty(exports, 'convertHex8ToRgba', {
+  enumerable: true,
+  get: function () {
+    return convertHex8ToRgba;
+  }
+});
+Object.defineProperty(exports, 'convertHexToHsl', {
+  enumerable: true,
+  get: function () {
+    return convertHexToHsl;
+  }
+});
+Object.defineProperty(exports, 'convertHexToRgb', {
+  enumerable: true,
+  get: function () {
+    return convertHexToRgb;
+  }
+});
+Object.defineProperty(exports, 'convertHslToHex', {
+  enumerable: true,
+  get: function () {
+    return convertHslToHex;
+  }
+});
+Object.defineProperty(exports, 'convertHslToRgb', {
+  enumerable: true,
+  get: function () {
+    return convertHslToRgb;
+  }
+});
+Object.defineProperty(exports, 'convertHslaToHex8', {
+  enumerable: true,
+  get: function () {
+    return convertHslaToHex8;
+  }
+});
+Object.defineProperty(exports, 'convertHslaToRgba', {
+  enumerable: true,
+  get: function () {
+    return convertHslaToRgba;
+  }
+});
+Object.defineProperty(exports, 'convertRgbToHex', {
+  enumerable: true,
+  get: function () {
+    return convertRgbToHex;
+  }
+});
+Object.defineProperty(exports, 'convertRgbToHsl', {
+  enumerable: true,
+  get: function () {
+    return convertRgbToHsl;
+  }
+});
+Object.defineProperty(exports, 'convertRgbToRgba', {
+  enumerable: true,
+  get: function () {
+    return convertRgbToRgba;
+  }
+});
+Object.defineProperty(exports, 'convertRgbaToHex8', {
+  enumerable: true,
+  get: function () {
+    return convertRgbaToHex8;
+  }
+});
+Object.defineProperty(exports, 'convertRgbaToHsla', {
+  enumerable: true,
+  get: function () {
+    return convertRgbaToHsla;
+  }
+});
+Object.defineProperty(exports, 'extractAlphaColorValues', {
+  enumerable: true,
+  get: function () {
+    return extractAlphaColorValues;
+  }
+});
+Object.defineProperty(exports, 'extractSolidColorValues', {
+  enumerable: true,
+  get: function () {
+    return extractSolidColorValues;
+  }
+});
+Object.defineProperty(exports, 'percentToHex', {
+  enumerable: true,
+  get: function () {
+    return percentToHex;
+  }
+});