toolbox-x 1.0.0

package/dist/colors.d.mts

@@ -0,0 +1,355 @@
+/**
+ * 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 { rn as Percent } from "./object-B0TV3eHx.mjs";
+import { C as RandomColorOptions, E as SolidValues, S as RandomColor, _ as Hex, a as AlphaValues, b as RGB, g as HSLA, h as HSL, l as ColorInputArray, n as $ColorType, t as Color, v as Hex6, w as RandomHexRGB, x as RGBA, y as Hex8 } from "./Color-D38Xrw65.mjs";
+
+//#region src/colors/convert.d.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)`).
+ */
+declare const convertHslToRgb: (h: number, s: number, l: number) => RGB;
+/**
+ * * 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%)`).
+ */
+declare const convertRgbToHsl: (r: number, g: number, b: number) => HSL;
+/**
+ * * 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`).
+ */
+declare const convertHslToHex: (h: number, s: number, l: number) => Hex6;
+/**
+ * * 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%)`).
+ */
+declare const convertHexToHsl: (hex: Hex6 | Hex) => HSL;
+/**
+ * * 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`).
+ */
+declare const convertRgbToHex: (r: number, g: number, b: number) => Hex6;
+/**
+ * * 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)`).
+ */
+declare const convertHexToRgb: (hex: Hex6 | Hex | string) => RGB;
+/**
+ * * 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)`).
+ */
+declare const convertRgbToRgba: (r: number, g: number, b: number, a?: number) => RGBA;
+/**
+ * * 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`).
+ */
+declare const convertRgbaToHex8: (r: number, g: number, b: number, a?: number) => Hex8;
+/**
+ * * 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)`).
+ */
+declare const convertHslaToRgba: (h: number, s: number, l: number, a?: number) => RGBA;
+/**
+ * * 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)`).
+ */
+declare const convertRgbaToHsla: (r: number, g: number, b: number, a?: number) => HSLA;
+/**
+ * * 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)`).
+ */
+declare const convertHex8ToRgba: (hex8: Hex8) => RGBA;
+/**
+ * * 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`).
+ */
+declare const convertHslaToHex8: (h: number, s: number, l: number, a?: number) => Hex8;
+/**
+ * * 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..
+ */
+declare const convertHex8ToHsla: (hex8: Hex8) => HSLA;
+/**
+ * * Converts a `Hex` color code to `RGB` and `HSL` formats.
+ * - `Special Note:` Cast the parameter to `Hex6` before converting to `RGB` and `HSL`.
+ * @example convertColorCode('#FFF122' as Hex6)
+ *
+ * @param color The `Hex` color code (e.g., `#3c6945`).
+ * @returns An object containing the `RGB` and `HSL` formats of the given `Hex` color.
+ */
+declare function convertColorCode(color: Hex6): {
+  rgb: RGB;
+  hsl: HSL;
+};
+/**
+ * * Converts an `RGB` color to `Hex` and `HSL` formats.
+ *
+ * @param color The `RGB` color string (e.g., `rgb(60, 105, 69)`).
+ * @returns An object containing the `Hex` and `HSL` formats of the given `RGB` color.
+ */
+declare function convertColorCode(color: RGB): {
+  hex: Hex6;
+  hsl: HSL;
+};
+/**
+ * * Converts an `HSL` color to `Hex` and `RGB` formats.
+ *
+ * @param color The `HSL` color string (e.g., `hsl(132, 27.27%, 32.35%)`).
+ * @returns An object containing the `Hex` and `RGB` formats of the given `HSL` color.
+ */
+declare function convertColorCode(color: HSL): {
+  hex: Hex6;
+  rgb: RGB;
+};
+/**
+ * * Converts a `Hex8` color code to `RGB` and `HSL` formats.
+ * - `Special Note:` Cast the parameter to `Hex8` before converting to `RGBA` and `HSLA`.
+ * @example convertColorCode('#FFF122DE' as Hex8)
+ *
+ * @param color The `Hex8` color code (e.g., `#3c6945`).
+ * @returns An object containing the `RGB` and `HSL` formats of the given `Hex8` color.
+ */
+declare function convertColorCode(color: Hex8): {
+  rgba: RGBA;
+  hsla: HSLA;
+};
+/**
+ * * Converts an `RGBA` color to `Hex8` and `HSLA` formats.
+ *
+ * @param color The `RGBA` color string (e.g., `rgb(60, 105, 69)`).
+ * @returns An object containing the `Hex8` and `HSLA` formats of the given `RGBA` color.
+ */
+declare function convertColorCode(color: RGBA): {
+  hex8: Hex8;
+  hsla: HSLA;
+};
+/**
+ * * Converts an `HSLA` color to `Hex8` and `RGBA` formats.
+ *
+ * @param color The `HSLA` color string (e.g., `hsl(132, 27.27%, 32.35%)`).
+ * @returns An object containing the `Hex8` and `RGBA` formats of the given `HSLA` color.
+ */
+declare function convertColorCode(color: HSLA): {
+  hex8: Hex8;
+  rgba: RGBA;
+};
+//#endregion
+//#region src/colors/initials.d.ts
+/**
+ *  * Generates a hex (`Hex8` format) color based on the first character (initial) of a string or number.
+ *
+ * - For numbers, it uses 10 predefined colors (0-9).
+ * - For letters, it uses 26 predefined colors (A-Z).
+ * - Invalid characters handled with a fallback color.
+ * @param input - A string or number.
+ * @param opacity - A value from 0 to 100 representing the opacity percentage.
+ * @returns A hex color for the first character of the provided string/number.
+ */
+declare function getColorForInitial(input: string | number, opacity?: Percent): Hex8;
+/**
+ *  * Generates an array of hex (`Hex8` format) colors based on the first character (initial) of an array of strings/numbers or even nested arrays of strings/numbers.
+ *
+ * - For numbers, it uses 10 predefined colors (0-9).
+ * - For letters, it uses 26 predefined colors (A-Z).
+ * - For empty array it returns all 36 colors.
+ * - Invalid characters and inputs are handled with a fallback color.
+ * @param input - A string, number, or an array of strings/numbers or even nested arrays of strings/numbers.
+ * @param opacity - A value from 0 to 100 representing the opacity percentage.
+ * @returns A hex color for a string/number, or an array of hex colors for each element of the provided array.
+ */
+declare function getColorForInitial(input: ColorInputArray, opacity?: Percent): Hex8[];
+//#endregion
+//#region src/colors/random.d.ts
+/**
+ * * Utility to generate a unique random HSL color.
+ *
+ * @param maxColors - The maximum number of recent colors to store in memory. Default is `16`.
+ * @returns Generated unique random color in `HSL` format.
+ */
+declare const generateRandomHSLColor: (maxColors?: number) => HSL;
+/**
+ * @deprecated For optimized performance and more flexibility, please consider using {@link generateRandomColor}.
+ *
+ * * Utility to generate a unique random color in `Hex6` and `RGB` format.
+ *
+ * @param maxColors - The maximum number of recent colors to store in memory. Default is `16`.
+ * @returns An object of generated unique random color in both `Hex` and `RGB` formats.
+ */
+declare const generateRandomColorInHexRGB: (maxColors?: number) => RandomHexRGB;
+/**
+ * * Generates a random unique color in one of three formats: `Hex6`, `RGB`, or `HSL`.
+ *
+ * @remarks
+ * - If no `options` or `colorType` option is provided, the function defaults to returning a color in `Hex6` format.
+ * - The `colorType` option determines the return type:
+ *   - `'hex'` → returns a `Hex6` string e.g. `'#34E2EF'`
+ *   - `'rgb'` → returns an `RGB` string e.g. `'hsl(223, 96%, 53%)'`
+ *   - `'hsl'` → returns an `HSL` string e.g. `'rgb(235, 159, 45)'`
+ * - The `maxColors` option controls how many recently generated colors are kept in memory to prevent repetition.
+ *   By default, this value is `16`. Increasing it allows more unique color variations before repeating.
+ *
+ * @param options - Configuration options for random color generation, including `colorType` and `maxColors`.
+ * @returns A random unique color in the specified format (`Hex6`, `RGB`, or `HSL`).
+ *
+ * @example
+ * const hex = generateRandomColor();
+ * // hex value with inferred type: Hex6
+ *
+ * const rgb = generateRandomColor({ colorType: 'rgb' });
+ * // rgb value with inferred type: RGB
+ *
+ * const hsl = generateRandomColor({ colorType: 'hsl', maxColors: 32 });
+ * // hsl value with inferred type: HSL, with a larger unique color memory pool
+ */
+declare function generateRandomColor<C extends $ColorType = 'hex'>(options?: RandomColorOptions<C>): RandomColor<C>;
+//#endregion
+//#region src/colors/utils.d.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]`
+ */
+declare function extractSolidColorValues(color: HSL | RGB): SolidValues;
+/**
+ * * 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]`
+ */
+declare function extractAlphaColorValues(color: HSLA | RGBA): AlphaValues;
+/**
+ * * 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)
+ */
+declare function percentToHex(percent: Percent): string;
+/**
+ * * 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).
+ * @returns The hex color string with the applied opacity in `#RRGGBBAA` format.
+ *
+ * @throws - {@link TypeError} If the provided color is not a valid hex color string.
+ *
+ * @remarks
+ * - If the input color is in `#RRGGBB` format, the function will append the opacity value to create a `#RRGGBBAA` string.
+ * - If the input color is already in `#RRGGBBAA` format, it will replace the existing alpha value with the new one.
+ * - The function validates that the input color is a valid hex color string and that the opacity value is a valid percentage before applying the opacity.
+ * - If the opacity value is invalid, it defaults to 100% opacity (i.e., "FF").
+ * - The resulting hex color string is in uppercase for consistency with common hex color formats.
+ *
+ * @example
+ * applyOpacityToHex("#FF5733", 50);   // Returns "#FF573380"
+ * applyOpacityToHex("#FF573380", 25);   // Returns "#FF573340"
+ */
+declare function applyOpacityToHex(color: Hex, opacity: Percent): Hex8;
+/**
+ * * 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 2-digit hex string.
+ * @returns The hex color string with the applied opacity in `#RRGGBBAA` format.
+ *
+ * @throws - {@link TypeError} If the provided color is not a valid hex color string.
+ *
+ * @remarks
+ * - If the input color is in `#RRGGBB` format, the function will append the opacity value to create a `#RRGGBBAA` string.
+ * - If the input color is already in `#RRGGBBAA` format, it will replace the existing alpha value with the new one.
+ * - The function validates that the input color is a valid hex color string and that the opacity value is a valid a 2-digit hex string before applying the opacity.
+ * - If the opacity value is invalid, it defaults to 100% opacity (i.e., "FF").
+ * - The resulting hex color string is in uppercase for consistency with common hex color formats.
+ *
+ * @example
+ * applyOpacityToHex("#FF5733", "80"); // Returns "#FF573380"
+ * applyOpacityToHex("#FF573380", "40"); // Returns "#FF573340"
+ */
+declare function applyOpacityToHex(color: Hex, opacity: string): Hex8;
+//#endregion
+export { Color, Color as Colour, applyOpacityToHex, convertColorCode, convertHex8ToHsla, convertHex8ToRgba, convertHexToHsl, convertHexToRgb, convertHslToHex, convertHslToRgb, convertHslaToHex8, convertHslaToRgba, convertRgbToHex, convertRgbToHsl, convertRgbToRgba, convertRgbaToHex8, convertRgbaToHsla, extractAlphaColorValues, extractSolidColorValues, generateRandomColor, generateRandomColor as getRandomColor, generateRandomColorInHexRGB, generateRandomHSLColor as generateRandomHSL, generateRandomHSLColor, generateRandomHSLColor as getRandomHSL, getColorForInitial, percentToHex };