toolbox-x 1.0.0

package/dist/convert-DhaUoPVU.mjs

@@ -0,0 +1,368 @@
+/**
+ * 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.
+ */
+
+import { a as isNonEmptyString, c as isNumber } from "./primitives-KsFUp3kQ.mjs";
+import { a as isHex8, c as _applyOpacity, d as _isValidAlpha, i as isHex6, n as isHSL, o as isRGB, r as isHSLA, s as isRGBA } from "./guards-3kaUX66g.mjs";
+
+//#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 (isHSL(color) || 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 (isHSLA(color) || 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 (isHex6(color) || isHex8(color)) {
+		const upperColor = color.toUpperCase();
+		if (isNumber(opacity)) return _applyOpacity(upperColor, percentToHex(opacity));
+		else if (isNonEmptyString(opacity) && /^[0-9A-Fa-f]{2}$/.test(opacity)) return _applyOpacity(upperColor, opacity.toUpperCase());
+		else return _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 (!_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 (!_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 (!_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 (!_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 (!_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 (isHex6(trimmedColor)) return {
+		rgb: convertHexToRgb(trimmedColor),
+		hsl: convertHexToHsl(trimmedColor)
+	};
+	if (isRGB(trimmedColor)) {
+		const rgbValues = extractSolidColorValues(trimmedColor);
+		return {
+			hex: convertRgbToHex(...rgbValues),
+			hsl: convertRgbToHsl(...rgbValues)
+		};
+	}
+	if (isHSL(trimmedColor)) {
+		const hslValues = extractSolidColorValues(trimmedColor);
+		return {
+			hex: convertHslToHex(...hslValues),
+			rgb: convertHslToRgb(...hslValues)
+		};
+	}
+	if (isHex8(trimmedColor)) return {
+		rgba: convertHex8ToRgba(trimmedColor),
+		hsla: convertHex8ToHsla(trimmedColor)
+	};
+	if (isRGBA(trimmedColor)) {
+		const rgbaValues = extractAlphaColorValues(trimmedColor);
+		return {
+			hex8: convertRgbaToHex8(...rgbaValues),
+			hsla: convertRgbaToHsla(...rgbaValues)
+		};
+	}
+	if (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
+export { extractSolidColorValues as _, convertHexToRgb as a, convertHslaToHex8 as c, convertRgbToHsl as d, convertRgbToRgba as f, extractAlphaColorValues as g, applyOpacityToHex as h, convertHexToHsl as i, convertHslaToRgba as l, convertRgbaToHsla as m, convertHex8ToHsla as n, convertHslToHex as o, convertRgbaToHex8 as p, convertHex8ToRgba as r, convertHslToRgb as s, convertColorCode as t, convertRgbToHex as u, percentToHex as v };