nhb-toolbox 4.0.36 → 4.0.40

package/dist/cjs/colors/Color.js

@@ -8,7 +8,7 @@ const hsl = (0, random_1.generateRandomHSLColor)();
 const { hex, rgb } = (0, convert_1.convertColorCode)(hsl);
 /**
  * * Class representing a color and its conversions among `Hex`, `Hex8` `RGB`, `RGBA`, `HSL` and `HSLA` formats.
- * * It has 1 instance method `applyOpacity()` to apply opacity to `Hex`, `Hex8` `RGB`, `RGBA`, `HSL` or `HSLA` color.
+ * * It has 13 instance methods to manipulate and play with the color values.
  * * It has 6 static methods that can be used to check if a color is in `Hex`, `Hex8` `RGB`, `RGBA`, `HSL` or `HSLA` format.
  *
  * @property hex - The color in `Hex` format.
@@ -41,7 +41,7 @@ class Color {
      * If no color is passed, a random color will be generated.
      *
      * Additionally:
-     * - Use `.applyOpacity(opacity)` to modify or add opacity to the color.
+     * - It has 13 instance methods to manipulate and play with the color values.
      * - Use static methods like `Color.isHex6(color)` to validate color strings.
      *
      * @param toConvert - An optional input color string in any supported format (`Hex`, `Hex8`, `RGB`, `RGBA`, `HSL`, or `HSLA`) to convert in all other (includes the current format) formats.
@@ -118,12 +118,12 @@ class Color {
         yield this.hsla;
     }
     /**
-     * * Applies or modifies the opacity of a color.
-     * - For solid colors (Hex6/RGB/HSL): Adds an alpha channel with the specified opacity
-     * - For alpha colors (Hex8/RGBA/HSLA): Updates the existing alpha channel
+     * @instance Applies or modifies the opacity of a color. Mutate the original instance.
+     * - For solid colors (Hex6/RGB/HSL): Adds an alpha channel with the specified opacity.
+     * - For alpha colors (Hex8/RGBA/HSLA): Updates the existing alpha channel.
      *
-     * @param opacity - A number between 0-100 representing the opacity percentage
-     * @returns An object containing all color formats with the applied opacity
+     * @param opacity - A number between 0-100 representing the opacity percentage.
+     * @returns A new instance of `Color` containing all color formats with the applied opacity.
      *
      * @example
      * const color = new Color("#ff0000");
@@ -141,14 +141,168 @@ class Color {
         const alphaDecimal = validOpacity / 100;
         const rgbValues = (0, helpers_1._extractSolidColorValues)(this.rgb);
         const hslValues = (0, helpers_1._extractSolidColorValues)(this.hsl);
-        return {
+        return Color.#fromParts({
             hex: this.hex.slice(0, 7).toUpperCase(),
             hex8: `${this.hex.slice(0, 7)}${alphaHex}`.toUpperCase(),
             rgb: `rgb(${rgbValues[0]}, ${rgbValues[1]}, ${rgbValues[2]})`,
             rgba: `rgba(${rgbValues[0]}, ${rgbValues[1]}, ${rgbValues[2]}, ${alphaDecimal})`,
             hsl: `hsl(${hslValues[0]}, ${hslValues[1]}%, ${hslValues[2]}%)`,
             hsla: `hsla(${hslValues[0]}, ${hslValues[1]}%, ${hslValues[2]}%, ${alphaDecimal})`,
+        });
+    }
+    /**
+     * @instance Darkens the color by reducing the lightness by the given percentage.
+     * @param percent - The percentage to darken (0–100).
+     * @returns A new `Color` instance with the modified darkness.
+     */
+    applyDarkness(percent) {
+        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        const newL = Math.max(0, l - percent);
+        const newHSL = `hsl(${h}, ${s}%, ${newL}%)`;
+        return new Color(newHSL);
+    }
+    /**
+     * @instance Lightens the color by increasing the lightness by the given percentage.
+     * @param percent - The percentage to brighten (0–100).
+     * @returns A new `Color` instance with the modified lightness.
+     */
+    applyBrightness(percent) {
+        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        const newL = Math.min(100, l + percent);
+        const newHSL = `hsl(${h}, ${s}%, ${newL}%)`;
+        return new Color(newHSL);
+    }
+    /**
+     * @instance Reduces the saturation of the color to make it appear duller.
+     * @param percent - The percentage to reduce saturation (0–100).
+     * @returns A new `Color` instance with the modified saturation.
+     */
+    applyDullness(percent) {
+        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        const newS = Math.max(0, s - percent);
+        const newHSL = `hsl(${h}, ${newS}%, ${l}%)`;
+        return new Color(newHSL);
+    }
+    /**
+     * @instance Softens the color toward white by reducing saturation and increasing lightness based on a percentage.
+     * - *This creates a soft UI-like white shade effect (similar to some UI libraries' light color scale).*
+     * @param percent - Value from 0 to 100 representing how far to push the color toward white.
+     * @returns A new `Color` instance shifted toward white.
+     */
+    applyWhiteShade(percent) {
+        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        // Cap values to avoid overshooting
+        const newS = Math.max(0, s - (s * percent) / 100);
+        const newL = Math.min(100, l + ((100 - l) * percent) / 100);
+        const newHSL = `hsl(${h}, ${newS}%, ${newL}%)`;
+        return new Color(newHSL);
+    }
+    /**
+     * @instance Blends the current color with another color based on the given weight.
+     * @param other - The color in any 6 `(Hex, Hex8 RGB, RGBA, HSL or HSLA)` to blend with.
+     * @param weight - A number from 0 to 1 indicating the weight of the other color. Defaults to `0.5`.
+     * 				 - `weight = 0` → only the original color (this)
+     *				 - `weight = 1` → only the other color
+     *				 - `weight = 0.5` → equal blend between the two
+     * @returns A new `Color` instance representing the blended result.
+     */
+    blendWith(other, weight = 0.5) {
+        const w = Math.max(0, Math.min(1, weight));
+        const converted = new Color(other);
+        const rgb1 = (0, helpers_1._extractSolidColorValues)(this.rgb);
+        const rgb2 = (0, helpers_1._extractSolidColorValues)(converted.rgb);
+        const blended = rgb1.map((c, i) => Math.round(c * (1 - w) + rgb2[i] * w));
+        const blendedRGB = `rgb(${blended[0]}, ${blended[1]}, ${blended[2]})`;
+        return new Color(blendedRGB);
+    }
+    /**
+     * @instance Calculates the contrast ratio between this color and another color (WCAG).
+     * @param other - The other color to compare against.
+     * @returns A number representing the contrast ratio (rounded to 2 decimal places).
+     */
+    contrastRatio(other) {
+        const newColor = new Color(other);
+        const luminance = (rgb) => {
+            const [r, g, b] = (0, helpers_1._extractSolidColorValues)(rgb).map((v) => {
+                const c = v / 255;
+                return c <= 0.03928 ?
+                    c / 12.92
+                    : Math.pow((c + 0.055) / 1.055, 2.4);
+            });
+            return 0.2126 * r + 0.7152 * g + 0.0722 * b;
         };
+        const lum1 = luminance(this.rgb);
+        const lum2 = luminance(newColor.rgb);
+        const brighter = Math.max(lum1, lum2);
+        const darker = Math.min(lum1, lum2);
+        const ratio = (brighter + 0.05) / (darker + 0.05);
+        return Math.round(ratio * 100) / 100;
+    }
+    /**
+     * @instance Returns the complementary color by rotating the hue 180 degrees.
+     * @returns A new Color that is the complement of the current color.
+     */
+    getComplementaryColor() {
+        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        const newHue = (h + 180) % 360;
+        const newHSL = `hsl(${newHue}, ${s}%, ${l}%)`;
+        return new Color(newHSL);
+    }
+    /**
+     * @instance Generates a color scheme of analogous colors, including the base color.
+     * Analogous colors are next to each other on the color wheel (±30°).
+     * @returns An array of three Color instances: [base, left, right].
+     */
+    getAnalogousColors() {
+        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        const left = `hsl(${(h + 330) % 360}, ${s}%, ${l}%)`;
+        const right = `hsl(${(h + 30) % 360}, ${s}%, ${l}%)`;
+        return [this, new Color(left), new Color(right)];
+    }
+    /**
+     * @instance Generates a color triad scheme including the base color.
+     * Triadic colors are evenly spaced (120° apart) on the color wheel.
+     * @returns An array of three Color instances: [base, triad1, triad2].
+     */
+    getTriadColors() {
+        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        const c1 = `hsl(${(h + 120) % 360}, ${s}%, ${l}%)`;
+        const c2 = `hsl(${(h + 240) % 360}, ${s}%, ${l}%)`;
+        return [this, new Color(c1), new Color(c2)];
+    }
+    /**
+     * @instance Generates a tetradic color scheme including the base color.
+     * Tetradic colors form a rectangle on the color wheel (90° apart).
+     * @returns An array of four Color instances: [base, tetrad1, tetrad2, tetrad3].
+     */
+    getTetradColors() {
+        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        const c1 = `hsl(${(h + 90) % 360}, ${s}%, ${l}%)`;
+        const c2 = `hsl(${(h + 180) % 360}, ${s}%, ${l}%)`;
+        const c3 = `hsl(${(h + 270) % 360}, ${s}%, ${l}%)`;
+        return [this, new Color(c1), new Color(c2), new Color(c3)];
+    }
+    /**
+     * @instance Gets the `WCAG` accessibility rating between this and another color.
+     * @param other - The other color to test contrast against.
+     * @returns 'Fail', 'AA', or 'AAA' based on `WCAG 2.1` contrast standards.
+     */
+    getWCAGRating(other) {
+        const ratio = this.contrastRatio(other);
+        if (ratio >= 7)
+            return 'AAA';
+        if (ratio >= 4.5)
+            return 'AA';
+        return 'Fail';
+    }
+    /**
+     * @instance Determines if the color is light based on its perceived brightness.
+     * @returns `true` if light, `false` if dark.
+     */
+    isLightColor() {
+        const [r, g, b] = (0, helpers_1._extractSolidColorValues)(this.rgb);
+        const brightness = (r * 299 + g * 587 + b * 114) / 1000;
+        return brightness > 127.5;
     }
     /**
      * @static Checks if a color is in `Hex6` format.
@@ -169,40 +323,40 @@ class Color {
         return /^#[0-9A-Fa-f]{8}$/.test(color);
     }
     /**
-     * @static Checks if a color is in `RGB` format.
+     * @static Checks if a color is in `RGB` format and within valid ranges.
      *
      * @param color Color to check.
-     * @returns Boolean: `true` if it's an `RGB` color, `false` if not.
+     * @returns `true` if it's a `RGB` color, `false` if not.
      */
     static isRGB(color) {
-        return /^rgb\(\d{1,3},\s*\d{1,3},\s*\d{1,3}\)$/.test(color);
+        return (0, helpers_1._isRGB)(color);
     }
     /**
-     * @static Checks if a color is in `RGBA` format.
+     * @static Checks if a color is in `RGBA` format and within valid ranges.
      *
      * @param color Color to check.
-     * @returns Boolean: `true` if it's an `RGBA` color, `false` if not.
+     * @returns `true` if it's a `RGBA` color, `false` if not.
      */
     static isRGBA(color) {
-        return /^rgba\(\d{1,3},\s*\d{1,3},\s*\d{1,3},\s*(0|1|0?\.\d+)\)$/.test(color);
+        return (0, helpers_1._isRGBA)(color);
     }
     /**
-     * @static Checks if a color is in `HSL` format.
+     * @static Checks if a color is in `HSL` format and within valid ranges.
      *
      * @param color Color to check.
-     * @returns Boolean: `true` if it's an `HSL` color, `false` if not.
+     * @returns `true` if it's a `HSL` color, `false` if not.
      */
     static isHSL(color) {
-        return /^hsl\(\d{1,3},\s*\d{1,3}%,\s*\d{1,3}%\)$/.test(color);
+        return (0, helpers_1._isHSL)(color);
     }
     /**
-     * @static Checks if a color is in `HSLA` format.
+     * @static Checks if a color is in `HSLA` format and within valid ranges.
      *
      * @param color Color to check.
-     * @returns Boolean: `true` if it's an `HSLA` color, `false` if not.
+     * @returns `true` if it's a `HSLA` color, `false` if not.
      */
     static isHSLA(color) {
-        return /^hsla\(\d{1,3},\s*\d{1,3}%,\s*\d{1,3}%,\s*(0|1|0?\.\d+)\)$/.test(color);
+        return (0, helpers_1._isHSLA)(color);
     }
     /**
      * @private Converts the given color to all other formats while preserving the original.
@@ -237,5 +391,20 @@ class Color {
         }
         throw new Error(`Unrecognized color format: ${color}`);
     }
+    /**
+     * @private @static Internal factory to create a Color instance from parsed parts.
+     * @param parts All the color parts as object.
+     * @returns An instance of `Color`.
+     */
+    static #fromParts(parts) {
+        const color = Object.create(Color.prototype);
+        color.hex = parts.hex;
+        color.hex8 = parts.hex8;
+        color.rgb = parts.rgb;
+        color.rgba = parts.rgba;
+        color.hsl = parts.hsl;
+        color.hsla = parts.hsla;
+        return color;
+    }
 }
 exports.Color = Color;

package/dist/cjs/colors/helpers.js

@@ -2,12 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports._extractAlphaColorValues = exports._extractSolidColorValues = exports._isSimilarToLast = exports._generateRandomHSL = exports._applyOpacity = exports._convertOpacityToHex = void 0;
 exports._isHex6 = _isHex6;
-exports._isRGB = _isRGB;
-exports._isHSL = _isHSL;
 exports._isHex8 = _isHex8;
+exports._isRGB = _isRGB;
 exports._isRGBA = _isRGBA;
+exports._isHSL = _isHSL;
 exports._isHSLA = _isHSLA;
 exports._isValidAlpha = _isValidAlpha;
+exports._isValidRGBComponent = _isValidRGBComponent;
+exports._isValidHue = _isValidHue;
+exports._isValidPercentage = _isValidPercentage;
 /**
  * * Converts opacity percentage (0-100) to a 2-digit hex string.
  *
@@ -97,7 +100,7 @@ const _extractAlphaColorValues = (colorString) => {
 };
 exports._extractAlphaColorValues = _extractAlphaColorValues;
 /**
- * * Checks if a color is in `Hex` format.
+ * @private Checks if a color is in `Hex` format.
  *
  * @param color Color to check.
  * @returns Boolean: `true` if it's a `Hex` color, `false` if not.
@@ -106,58 +109,92 @@ function _isHex6(color) {
     return /^#[0-9A-Fa-f]{6}$/.test(color);
 }
 /**
- * * Checks if a color is in `RGB` format.
+ * @private Checks if a color is in `Hex8` format.
  *
  * @param color Color to check.
- * @returns Boolean: `true` if it's an `RGB` color, `false` if not.
+ * @returns Boolean: `true` if it's a `Hex8` color, `false` if not.
  */
-function _isRGB(color) {
-    return /^rgb\(\d{1,3},\s*\d{1,3},\s*\d{1,3}\)$/.test(color);
+function _isHex8(color) {
+    return /^#[0-9A-Fa-f]{8}$/.test(color);
 }
 /**
- * * Checks if a color is in `HSL` format.
+ * @private Checks if a color is in `RGB` format and within valid ranges.
  *
  * @param color Color to check.
- * @returns Boolean: `true` if it's an `HSL` color, `false` if not.
+ * @returns `true` if it's a `RGB` color, `false` if not.
  */
-function _isHSL(color) {
-    return /^hsl\(\d{1,3},\s*\d{1,3}%,\s*\d{1,3}%\)$/.test(color);
+function _isRGB(color) {
+    const match = color.match(/^rgb\(\s*(\d{1,3}(?:\.\d+)?),\s*(\d{1,3}(?:\.\d+)?),\s*(\d{1,3}(?:\.\d+)?)\s*\)$/);
+    if (!match)
+        return false;
+    const [r, g, b] = match.slice(1).map(Number);
+    return (_isValidRGBComponent(r) &&
+        _isValidRGBComponent(g) &&
+        _isValidRGBComponent(b));
 }
 /**
- * @static
- * Checks if a color is in `Hex8` format.
+ * @private Checks if a color is in `RGBA` format and within valid ranges.
  *
  * @param color Color to check.
- * @returns Boolean: `true` if it's a `Hex8` color, `false` if not.
+ * @returns `true` if it's a `RGBA` color, `false` if not.
  */
-function _isHex8(color) {
-    return /^#[0-9A-Fa-f]{8}$/.test(color);
+function _isRGBA(color) {
+    const match = color.match(/^rgba\(\s*(\d{1,3}(?:\.\d+)?),\s*(\d{1,3}(?:\.\d+)?),\s*(\d{1,3}(?:\.\d+)?),\s*(0|1|0?\.\d+)\s*\)$/);
+    if (!match)
+        return false;
+    const [r, g, b, a] = match.slice(1).map(Number);
+    return (_isValidRGBComponent(r) &&
+        _isValidRGBComponent(g) &&
+        _isValidRGBComponent(b) &&
+        _isValidAlpha(a));
 }
 /**
- * @static
- * Checks if a color is in `RGBA` format.
+ * @private Checks if a color is in `HSL` format and within valid ranges.
  *
  * @param color Color to check.
- * @returns Boolean: `true` if it's an `RGBA` color, `false` if not.
+ * @returns `true` if it's a `HSL` color, `false` if not.
  */
-function _isRGBA(color) {
-    return /^rgba\(\d{1,3},\s*\d{1,3},\s*\d{1,3},\s*(0|1|0?\.\d+)\)$/.test(color);
+function _isHSL(color) {
+    const match = color.match(/^hsl\(\s*(\d{1,3}(?:\.\d+)?),\s*(\d{1,3}(?:\.\d+)?)%,\s*(\d{1,3}(?:\.\d+)?)%\s*\)$/);
+    if (!match)
+        return false;
+    const [h, s, l] = match.slice(1).map(Number);
+    return _isValidHue(h) && _isValidPercentage(s) && _isValidPercentage(l);
 }
 /**
- * @static
- * Checks if a color is in `HSLA` format.
+ * @private Checks if a color is in `HSLA` format and within valid ranges.
  *
  * @param color Color to check.
- * @returns Boolean: `true` if it's an `HSLA` color, `false` if not.
+ * @returns `true` if it's a `HSLA` color, `false` if not.
  */
 function _isHSLA(color) {
-    return /^hsla\(\d{1,3},\s*\d{1,3}%,\s*\d{1,3}%,\s*(0|1|0?\.\d+)\)$/.test(color);
+    const match = color.match(/^hsla\(\s*(\d{1,3}(?:\.\d+)?),\s*(\d{1,3}(?:\.\d+)?)%,\s*(\d{1,3}(?:\.\d+)?)%,\s*(0|1|0?\.\d+)\s*\)$/);
+    if (!match)
+        return false;
+    const [h, s, l, a] = match.slice(1).map(Number);
+    return (_isValidHue(h) &&
+        _isValidPercentage(s) &&
+        _isValidPercentage(l) &&
+        _isValidAlpha(a));
 }
 /**
- * * Type guard to validate alpha value.
+ * @private Checks if a number is valid alpha value.
+ *
  * @param value Alpha value to check.
- * @returns Boolean: `true` if it's a valid alpha value, `false` if not.
+ * @returns `true` if it's a valid alpha value, `false` if not.
  */
 function _isValidAlpha(value) {
     return value >= 0 && value <= 1 && !isNaN(value);
 }
+/** * @private Validates RGB component (0–255). */
+function _isValidRGBComponent(value) {
+    return value >= 0 && value <= 255;
+}
+/** * @private Validates HSL hue (0–360). */
+function _isValidHue(value) {
+    return value >= 0 && value <= 360;
+}
+/** * @private Validates HSL percentage components (0–100). */
+function _isValidPercentage(value) {
+    return value >= 0 && value <= 100;
+}

package/dist/dts/colors/Color.d.ts

@@ -1,7 +1,7 @@
-import type { AlphaColors, ColorType, Hex6, Hex8, HSL, HSLA, OpacityValue, RGB, RGBA, SolidColors } from './types';
+import type { ColorType, Hex6, Hex8, HSL, HSLA, Percent, RGB, RGBA } from './types';
 /**
  * * Class representing a color and its conversions among `Hex`, `Hex8` `RGB`, `RGBA`, `HSL` and `HSLA` formats.
- * * It has 1 instance method `applyOpacity()` to apply opacity to `Hex`, `Hex8` `RGB`, `RGBA`, `HSL` or `HSLA` color.
+ * * It has 13 instance methods to manipulate and play with the color values.
  * * It has 6 static methods that can be used to check if a color is in `Hex`, `Hex8` `RGB`, `RGBA`, `HSL` or `HSLA` format.
  *
  * @property hex - The color in `Hex` format.
@@ -32,7 +32,7 @@ export declare class Color {
      * - `HSLA` (e.g., `hsla(14, 100%, 60%, 1)`)
      *
      * Additionally:
-     * - Use `.applyOpacity(opacity)` to modify or add opacity to the color.
+     * - It has 13 instance methods to manipulate and play with the color values.
      * - Use static methods like `Color.isHex6(color)` to validate color strings.
      *
      * @example
@@ -58,7 +58,7 @@ export declare class Color {
      * You can create a color from any of these formats, and the class will populate the rest.
      *
      * Additionally:
-     * - Use `.applyOpacity(opacity)` to modify or add opacity to the color.
+     * - It has 13 instance methods to manipulate and play with the color values.
      * - Use available 6 static methods like `Color.isHex6(color)` to validate color strings.
      *
      * @param toConvert - A color string in any supported format (`Hex`, `Hex8`, `RGB`, `RGBA`, `HSL`, or `HSLA`) to convert in all other formats (includes the current format).
@@ -84,12 +84,12 @@ export declare class Color {
     /** - Iterates over the color representations (Hex, RGB, HSL). */
     [Symbol.iterator](): Generator<Hex6 | RGB | HSL | Hex8 | RGBA | HSLA, void, unknown>;
     /**
-     * * Applies or modifies the opacity of a color.
-     * - For solid colors (Hex6/RGB/HSL): Adds an alpha channel with the specified opacity
-     * - For alpha colors (Hex8/RGBA/HSLA): Updates the existing alpha channel
+     * @instance Applies or modifies the opacity of a color. Mutate the original instance.
+     * - For solid colors (Hex6/RGB/HSL): Adds an alpha channel with the specified opacity.
+     * - For alpha colors (Hex8/RGBA/HSLA): Updates the existing alpha channel.
      *
-     * @param opacity - A number between 0-100 representing the opacity percentage
-     * @returns An object containing all color formats with the applied opacity
+     * @param opacity - A number between 0-100 representing the opacity percentage.
+     * @returns A new instance of `Color` containing all color formats with the applied opacity.
      *
      * @example
      * const color = new Color("#ff0000");
@@ -101,7 +101,82 @@ export declare class Color {
      * const alpha75 = alphaColor.applyOpacity(75); // Change to 75% opacity
      * console.log(alpha75.hex8); // #FF0000BF
      */
-    applyOpacity(opacity: OpacityValue): SolidColors & AlphaColors;
+    applyOpacity(opacity: Percent): Color;
+    /**
+     * @instance Darkens the color by reducing the lightness by the given percentage.
+     * @param percent - The percentage to darken (0–100).
+     * @returns A new `Color` instance with the modified darkness.
+     */
+    applyDarkness(percent: Percent): Color;
+    /**
+     * @instance Lightens the color by increasing the lightness by the given percentage.
+     * @param percent - The percentage to brighten (0–100).
+     * @returns A new `Color` instance with the modified lightness.
+     */
+    applyBrightness(percent: Percent): Color;
+    /**
+     * @instance Reduces the saturation of the color to make it appear duller.
+     * @param percent - The percentage to reduce saturation (0–100).
+     * @returns A new `Color` instance with the modified saturation.
+     */
+    applyDullness(percent: Percent): Color;
+    /**
+     * @instance Softens the color toward white by reducing saturation and increasing lightness based on a percentage.
+     * - *This creates a soft UI-like white shade effect (similar to some UI libraries' light color scale).*
+     * @param percent - Value from 0 to 100 representing how far to push the color toward white.
+     * @returns A new `Color` instance shifted toward white.
+     */
+    applyWhiteShade(percent: Percent): Color;
+    /**
+     * @instance Blends the current color with another color based on the given weight.
+     * @param other - The color in any 6 `(Hex, Hex8 RGB, RGBA, HSL or HSLA)` to blend with.
+     * @param weight - A number from 0 to 1 indicating the weight of the other color. Defaults to `0.5`.
+     * 				 - `weight = 0` → only the original color (this)
+     *				 - `weight = 1` → only the other color
+     *				 - `weight = 0.5` → equal blend between the two
+     * @returns A new `Color` instance representing the blended result.
+     */
+    blendWith(other: ColorType, weight?: number): Color;
+    /**
+     * @instance Calculates the contrast ratio between this color and another color (WCAG).
+     * @param other - The other color to compare against.
+     * @returns A number representing the contrast ratio (rounded to 2 decimal places).
+     */
+    contrastRatio(other: ColorType): number;
+    /**
+     * @instance Returns the complementary color by rotating the hue 180 degrees.
+     * @returns A new Color that is the complement of the current color.
+     */
+    getComplementaryColor(): Color;
+    /**
+     * @instance Generates a color scheme of analogous colors, including the base color.
+     * Analogous colors are next to each other on the color wheel (±30°).
+     * @returns An array of three Color instances: [base, left, right].
+     */
+    getAnalogousColors(): [Color, Color, Color];
+    /**
+     * @instance Generates a color triad scheme including the base color.
+     * Triadic colors are evenly spaced (120° apart) on the color wheel.
+     * @returns An array of three Color instances: [base, triad1, triad2].
+     */
+    getTriadColors(): [Color, Color, Color];
+    /**
+     * @instance Generates a tetradic color scheme including the base color.
+     * Tetradic colors form a rectangle on the color wheel (90° apart).
+     * @returns An array of four Color instances: [base, tetrad1, tetrad2, tetrad3].
+     */
+    getTetradColors(): [Color, Color, Color, Color];
+    /**
+     * @instance Gets the `WCAG` accessibility rating between this and another color.
+     * @param other - The other color to test contrast against.
+     * @returns 'Fail', 'AA', or 'AAA' based on `WCAG 2.1` contrast standards.
+     */
+    getWCAGRating(other: ColorType): 'Fail' | 'AA' | 'AAA';
+    /**
+     * @instance Determines if the color is light based on its perceived brightness.
+     * @returns `true` if light, `false` if dark.
+     */
+    isLightColor(): boolean;
     /**
      * @static Checks if a color is in `Hex6` format.
      *
@@ -117,31 +192,31 @@ export declare class Color {
      */
     static isHex8(color: string): color is Hex8;
     /**
-     * @static Checks if a color is in `RGB` format.
+     * @static Checks if a color is in `RGB` format and within valid ranges.
      *
      * @param color Color to check.
-     * @returns Boolean: `true` if it's an `RGB` color, `false` if not.
+     * @returns `true` if it's a `RGB` color, `false` if not.
      */
     static isRGB(color: string): color is RGB;
     /**
-     * @static Checks if a color is in `RGBA` format.
+     * @static Checks if a color is in `RGBA` format and within valid ranges.
      *
      * @param color Color to check.
-     * @returns Boolean: `true` if it's an `RGBA` color, `false` if not.
+     * @returns `true` if it's a `RGBA` color, `false` if not.
      */
     static isRGBA(color: string): color is RGBA;
     /**
-     * @static Checks if a color is in `HSL` format.
+     * @static Checks if a color is in `HSL` format and within valid ranges.
      *
      * @param color Color to check.
-     * @returns Boolean: `true` if it's an `HSL` color, `false` if not.
+     * @returns `true` if it's a `HSL` color, `false` if not.
      */
     static isHSL(color: string): color is HSL;
     /**
-     * @static Checks if a color is in `HSLA` format.
+     * @static Checks if a color is in `HSLA` format and within valid ranges.
      *
      * @param color Color to check.
-     * @returns Boolean: `true` if it's an `HSLA` color, `false` if not.
+     * @returns `true` if it's a `HSLA` color, `false` if not.
      */
     static isHSLA(color: string): color is HSLA;
 }

package/dist/dts/colors/Color.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Color.d.ts","sourceRoot":"","sources":["../../../src/colors/Color.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACX,WAAW,EACX,SAAS,EACT,IAAI,EACJ,IAAI,EACJ,GAAG,EACH,IAAI,EACJ,YAAY,EACZ,GAAG,EACH,IAAI,EACJ,WAAW,EACX,MAAM,SAAS,CAAC;AAKjB;;;;;;;;;;;GAWG;AACH,qBAAa,KAAK;;IACV,GAAG,EAAE,IAAI,CAAC;IACV,IAAI,EAAE,IAAI,CAAC;IACX,GAAG,EAAE,GAAG,CAAC;IACT,IAAI,EAAE,IAAI,CAAC;IACX,GAAG,EAAE,GAAG,CAAC;IACT,IAAI,EAAE,IAAI,CAAC;IAElB;;;;;;;;;;;;;;;;;;;;;;OAsBG;;IAGH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;gBACS,SAAS,EAAE,SAAS;IAwFhC,iEAAiE;IAChE,CAAC,MAAM,CAAC,QAAQ,CAAC;IASlB;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,WAAW,GAAG,WAAW;IAkB9D;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI;IAI3C;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI;IAI3C;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,GAAG;IAIzC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI;IAM3C;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,GAAG;IAIzC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI;CAmC3C"}
+{"version":3,"file":"Color.d.ts","sourceRoot":"","sources":["../../../src/colors/Color.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAIX,SAAS,EACT,IAAI,EACJ,IAAI,EACJ,GAAG,EACH,IAAI,EACJ,OAAO,EACP,GAAG,EACH,IAAI,EAEJ,MAAM,SAAS,CAAC;AAKjB;;;;;;;;;;;GAWG;AACH,qBAAa,KAAK;;IACV,GAAG,EAAE,IAAI,CAAC;IACV,IAAI,EAAE,IAAI,CAAC;IACX,GAAG,EAAE,GAAG,CAAC;IACT,IAAI,EAAE,IAAI,CAAC;IACX,GAAG,EAAE,GAAG,CAAC;IACT,IAAI,EAAE,IAAI,CAAC;IAElB;;;;;;;;;;;;;;;;;;;;;;OAsBG;;IAGH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;gBACS,SAAS,EAAE,SAAS;IAwFhC,iEAAiE;IAChE,CAAC,MAAM,CAAC,QAAQ,CAAC;IASlB;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,KAAK;IAkBrC;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,KAAK;IAUtC;;;;OAIG;IACH,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,KAAK;IAUxC;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,KAAK;IAUtC;;;;;OAKG;IACH,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,KAAK;IAYxC;;;;;;;;OAQG;IACH,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,SAAM,GAAG,KAAK;IAgBhD;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM;IAyBvC;;;OAGG;IACH,qBAAqB,IAAI,KAAK;IAU9B;;;;OAIG;IACH,kBAAkB,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC;IAS3C;;;;OAIG;IACH,cAAc,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC;IASvC;;;;OAIG;IACH,eAAe,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC;IAU/C;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,GAAG,KAAK;IAQtD;;;OAGG;IACH,YAAY,IAAI,OAAO;IAQvB;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI;IAI3C;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI;IAI3C;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,GAAG;IAIzC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI;IAI3C;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,GAAG;IAIzC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI;CAkD3C"}

package/dist/dts/colors/helpers.d.ts

@@ -1,11 +1,11 @@
-import type { AlphaValue, ColorNumbers, ColorNumbersAlpha, Hex6, Hex8, HSL, HSLA, OpacityValue, RGB, RGBA } from './types';
+import type { AlphaValue, ColorNumbers, ColorNumbersAlpha, Hex6, Hex8, HSL, HSLA, Percent, RGB, RGBA } from './types';
 /**
  * * Converts opacity percentage (0-100) to a 2-digit hex string.
  *
  * @param opacity - The opacity value as a percentage (0-100).
  * @returns A 2-digit hex string representing the alpha value.
  */
-export declare const _convertOpacityToHex: (opacity: OpacityValue) => string;
+export declare const _convertOpacityToHex: (opacity: Percent) => string;
 /**
  * * Applies an opacity value to a color string.
  * @param color The color string to apply opacity to.
@@ -45,54 +45,58 @@ export declare const _extractSolidColorValues: (colorString: HSL | RGB) => Color
  */
 export declare const _extractAlphaColorValues: (colorString: HSLA | RGBA) => ColorNumbersAlpha;
 /**
- * * Checks if a color is in `Hex` format.
+ * @private Checks if a color is in `Hex` format.
  *
  * @param color Color to check.
  * @returns Boolean: `true` if it's a `Hex` color, `false` if not.
  */
 export declare function _isHex6(color: string): color is Hex6;
 /**
- * * Checks if a color is in `RGB` format.
+ * @private Checks if a color is in `Hex8` format.
  *
  * @param color Color to check.
- * @returns Boolean: `true` if it's an `RGB` color, `false` if not.
+ * @returns Boolean: `true` if it's a `Hex8` color, `false` if not.
  */
-export declare function _isRGB(color: string): color is RGB;
+export declare function _isHex8(color: string): color is Hex8;
 /**
- * * Checks if a color is in `HSL` format.
+ * @private Checks if a color is in `RGB` format and within valid ranges.
  *
  * @param color Color to check.
- * @returns Boolean: `true` if it's an `HSL` color, `false` if not.
+ * @returns `true` if it's a `RGB` color, `false` if not.
  */
-export declare function _isHSL(color: string): color is HSL;
+export declare function _isRGB(color: string): color is RGB;
 /**
- * @static
- * Checks if a color is in `Hex8` format.
+ * @private Checks if a color is in `RGBA` format and within valid ranges.
  *
  * @param color Color to check.
- * @returns Boolean: `true` if it's a `Hex8` color, `false` if not.
+ * @returns `true` if it's a `RGBA` color, `false` if not.
  */
-export declare function _isHex8(color: string): color is Hex8;
+export declare function _isRGBA(color: string): color is RGBA;
 /**
- * @static
- * Checks if a color is in `RGBA` format.
+ * @private Checks if a color is in `HSL` format and within valid ranges.
  *
  * @param color Color to check.
- * @returns Boolean: `true` if it's an `RGBA` color, `false` if not.
+ * @returns `true` if it's a `HSL` color, `false` if not.
  */
-export declare function _isRGBA(color: string): color is RGBA;
+export declare function _isHSL(color: string): color is HSL;
 /**
- * @static
- * Checks if a color is in `HSLA` format.
+ * @private Checks if a color is in `HSLA` format and within valid ranges.
  *
  * @param color Color to check.
- * @returns Boolean: `true` if it's an `HSLA` color, `false` if not.
+ * @returns `true` if it's a `HSLA` color, `false` if not.
  */
 export declare function _isHSLA(color: string): color is HSLA;
 /**
- * * Type guard to validate alpha value.
+ * @private Checks if a number is valid alpha value.
+ *
  * @param value Alpha value to check.
- * @returns Boolean: `true` if it's a valid alpha value, `false` if not.
+ * @returns `true` if it's a valid alpha value, `false` if not.
  */
 export declare function _isValidAlpha(value: number): value is AlphaValue;
+/** * @private Validates RGB component (0–255). */
+export declare function _isValidRGBComponent(value: number): boolean;
+/** * @private Validates HSL hue (0–360). */
+export declare function _isValidHue(value: number): boolean;
+/** * @private Validates HSL percentage components (0–100). */
+export declare function _isValidPercentage(value: number): boolean;
 //# sourceMappingURL=helpers.d.ts.map

package/dist/dts/colors/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/colors/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,IAAI,EACJ,IAAI,EACJ,GAAG,EACH,IAAI,EACJ,YAAY,EACZ,GAAG,EACH,IAAI,EACJ,MAAM,SAAS,CAAC;AAEjB;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,YAAa,YAAY,KAAG,MAO5D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,UAAW,MAAM,WAAW,MAAM,KAAG,MAE9D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QAAO,GAKrC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,iBACd,MAAM,EAAE,YACZ,MAAM,KACd,OA2BF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,gBACvB,GAAG,GAAG,GAAG,KACpB,YAIF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,gBACvB,IAAI,GAAG,IAAI,KACtB,iBAIF,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,GAAG,CAElD;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,GAAG,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI,CAIpD;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI,CAIpD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAEhE"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/colors/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,IAAI,EACJ,IAAI,EACJ,GAAG,EACH,IAAI,EACJ,OAAO,EACP,GAAG,EACH,IAAI,EACJ,MAAM,SAAS,CAAC;AAEjB;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,YAAa,OAAO,KAAG,MAOvD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,UAAW,MAAM,WAAW,MAAM,KAAG,MAE9D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QAAO,GAKrC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,iBACd,MAAM,EAAE,YACZ,MAAM,KACd,OA2BF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,gBACvB,GAAG,GAAG,GAAG,KACpB,YAIF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,gBACvB,IAAI,GAAG,IAAI,KACtB,iBAIF,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,GAAG,CAWlD;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI,CAYpD;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,GAAG,CAOlD;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI,CAYpD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAEhE;AAED,kDAAkD;AAClD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED,4CAA4C;AAC5C,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAElD;AAED,8DAA8D;AAC9D,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEzD"}

package/dist/dts/colors/initials.d.ts

@@ -1,4 +1,4 @@
-import type { ColorInputArray, OpacityValue } from './types';
+import type { ColorInputArray, Percent } from './types';
 /**
  *  * Generates a hex color based on the first character (initial) of a string or number.
  *
@@ -9,7 +9,7 @@ import type { ColorInputArray, OpacityValue } from './types';
  * @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.
  */
-export declare function getColorForInitial(input: string | number, opacity?: OpacityValue): string;
+export declare function getColorForInitial(input: string | number, opacity?: Percent): string;
 /**
  *  * Generates an array of hex colors based on the first character (initial) of an array of strings/numbers or even nested arrays of strings/numbers.
  *
@@ -21,5 +21,5 @@ export declare function getColorForInitial(input: string | number, opacity?: Opa
  * @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.
  */
-export declare function getColorForInitial(input: ColorInputArray, opacity?: OpacityValue): string[];
+export declare function getColorForInitial(input: ColorInputArray, opacity?: Percent): string[];
 //# sourceMappingURL=initials.d.ts.map

package/dist/dts/colors/initials.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"initials.d.ts","sourceRoot":"","sources":["../../../src/colors/initials.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAc,eAAe,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEzE;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,CAAC,EAAE,YAAY,GACpB,MAAM,CAAC;AAEV;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,eAAe,EACtB,OAAO,CAAC,EAAE,YAAY,GACpB,MAAM,EAAE,CAAC"}
+{"version":3,"file":"initials.d.ts","sourceRoot":"","sources":["../../../src/colors/initials.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAc,eAAe,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEpE;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,CAAC,EAAE,OAAO,GACf,MAAM,CAAC;AAEV;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,eAAe,EACtB,OAAO,CAAC,EAAE,OAAO,GACf,MAAM,EAAE,CAAC"}

package/dist/dts/colors/types.d.ts

@@ -4,8 +4,8 @@ export type ColorInput = string | number;
 /** - An array of strings/numbers or nested arrays of strings/numbers for generating colors. */
 export interface ColorInputArray extends Array<ColorInput | ColorInputArray> {
 }
-/** - Opacity value in percentage `(0% - 100%)` without `%` symbol. */
-export type OpacityValue = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100;
+/** - Number value in percentage `(0% - 100%)` without `%` symbol. */
+export type Percent = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100;
 /**
  * * Represents a hexadecimal color code.
  * * Format: `#3C6945`
@@ -100,4 +100,19 @@ export interface ConvertedColors<T extends ColorType> extends Record<string, Col
 }
 /** Represents an alpha value between 0 and 1 */
 export type AlphaValue = Branded<number, 'AlphaValue'>;
+/** An Object representing all the colors from `Color` constructor. */
+export interface Colors {
+    /** - `Hex` color (e.g., `#ff5733`) */
+    hex: Hex6;
+    /** - `Hex8` color (Hex with opacity, e.g., `#ff573380`) */
+    hex8: Hex8;
+    /** - `RGB` color (e.g., `rgb(255, 87, 51)`) */
+    rgb: RGB;
+    /** - `RGBA` color (e.g., `rgba(255, 87, 51, 1)`) */
+    rgba: RGBA;
+    /** - `HSL` color (e.g., `hsl(14, 100%, 60%)`) */
+    hsl: HSL;
+    /** - `HSLA` color (e.g., `hsla(14, 100%, 60%, 1)`) */
+    hsla: HSLA;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/dts/colors/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/colors/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/colors/types.ts"],"names":[],"mappings":"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"}

package/dist/dts/date/constants.d.ts

@@ -11,7 +11,7 @@ export declare const MINUTE_FORMATS: readonly ["mm", "m"];
 export declare const SECOND_FORMATS: readonly ["ss", "s"];
 export declare const MILLISECOND_FORMATS: readonly ["ms", "mss"];
 export declare const TIME_FORMATS: readonly ["a", "A"];
-export declare const sortedFormats: ("a" | "M" | "D" | "A" | "YYYY" | "YY" | "yyyy" | "yy" | "MM" | "mmm" | "mmmm" | "DD" | "Do" | "d" | "dd" | "ddd" | "H" | "HH" | "hh" | "h" | "mm" | "m" | "ss" | "s" | "ms" | "mss")[];
+export declare const sortedFormats: ("a" | "M" | "D" | "h" | "s" | "A" | "YYYY" | "YY" | "yyyy" | "yy" | "MM" | "mmm" | "mmmm" | "DD" | "Do" | "d" | "dd" | "ddd" | "H" | "HH" | "hh" | "mm" | "m" | "ss" | "ms" | "mss")[];
 export declare const TIME_ZONES: {
     /** International Date Line West (Baker Island, Howland Island) */
     readonly IDLW: number;

package/dist/esm/colors/Color.js

@@ -1,11 +1,11 @@
 import { convertColorCode } from './convert';
-import { _convertOpacityToHex, _extractAlphaColorValues, _extractSolidColorValues, } from './helpers';
+import { _convertOpacityToHex, _extractAlphaColorValues, _extractSolidColorValues, _isHSL, _isHSLA, _isRGB, _isRGBA, } from './helpers';
 import { generateRandomHSLColor } from './random';
 const hsl = generateRandomHSLColor();
 const { hex, rgb } = convertColorCode(hsl);
 /**
  * * Class representing a color and its conversions among `Hex`, `Hex8` `RGB`, `RGBA`, `HSL` and `HSLA` formats.
- * * It has 1 instance method `applyOpacity()` to apply opacity to `Hex`, `Hex8` `RGB`, `RGBA`, `HSL` or `HSLA` color.
+ * * It has 13 instance methods to manipulate and play with the color values.
  * * It has 6 static methods that can be used to check if a color is in `Hex`, `Hex8` `RGB`, `RGBA`, `HSL` or `HSLA` format.
  *
  * @property hex - The color in `Hex` format.
@@ -38,7 +38,7 @@ export class Color {
      * If no color is passed, a random color will be generated.
      *
      * Additionally:
-     * - Use `.applyOpacity(opacity)` to modify or add opacity to the color.
+     * - It has 13 instance methods to manipulate and play with the color values.
      * - Use static methods like `Color.isHex6(color)` to validate color strings.
      *
      * @param toConvert - An optional input color string in any supported format (`Hex`, `Hex8`, `RGB`, `RGBA`, `HSL`, or `HSLA`) to convert in all other (includes the current format) formats.
@@ -115,12 +115,12 @@ export class Color {
         yield this.hsla;
     }
     /**
-     * * Applies or modifies the opacity of a color.
-     * - For solid colors (Hex6/RGB/HSL): Adds an alpha channel with the specified opacity
-     * - For alpha colors (Hex8/RGBA/HSLA): Updates the existing alpha channel
+     * @instance Applies or modifies the opacity of a color. Mutate the original instance.
+     * - For solid colors (Hex6/RGB/HSL): Adds an alpha channel with the specified opacity.
+     * - For alpha colors (Hex8/RGBA/HSLA): Updates the existing alpha channel.
      *
-     * @param opacity - A number between 0-100 representing the opacity percentage
-     * @returns An object containing all color formats with the applied opacity
+     * @param opacity - A number between 0-100 representing the opacity percentage.
+     * @returns A new instance of `Color` containing all color formats with the applied opacity.
      *
      * @example
      * const color = new Color("#ff0000");
@@ -138,14 +138,168 @@ export class Color {
         const alphaDecimal = validOpacity / 100;
         const rgbValues = _extractSolidColorValues(this.rgb);
         const hslValues = _extractSolidColorValues(this.hsl);
-        return {
+        return Color.#fromParts({
             hex: this.hex.slice(0, 7).toUpperCase(),
             hex8: `${this.hex.slice(0, 7)}${alphaHex}`.toUpperCase(),
             rgb: `rgb(${rgbValues[0]}, ${rgbValues[1]}, ${rgbValues[2]})`,
             rgba: `rgba(${rgbValues[0]}, ${rgbValues[1]}, ${rgbValues[2]}, ${alphaDecimal})`,
             hsl: `hsl(${hslValues[0]}, ${hslValues[1]}%, ${hslValues[2]}%)`,
             hsla: `hsla(${hslValues[0]}, ${hslValues[1]}%, ${hslValues[2]}%, ${alphaDecimal})`,
+        });
+    }
+    /**
+     * @instance Darkens the color by reducing the lightness by the given percentage.
+     * @param percent - The percentage to darken (0–100).
+     * @returns A new `Color` instance with the modified darkness.
+     */
+    applyDarkness(percent) {
+        const [h, s, l] = _extractSolidColorValues(this.hsl);
+        const newL = Math.max(0, l - percent);
+        const newHSL = `hsl(${h}, ${s}%, ${newL}%)`;
+        return new Color(newHSL);
+    }
+    /**
+     * @instance Lightens the color by increasing the lightness by the given percentage.
+     * @param percent - The percentage to brighten (0–100).
+     * @returns A new `Color` instance with the modified lightness.
+     */
+    applyBrightness(percent) {
+        const [h, s, l] = _extractSolidColorValues(this.hsl);
+        const newL = Math.min(100, l + percent);
+        const newHSL = `hsl(${h}, ${s}%, ${newL}%)`;
+        return new Color(newHSL);
+    }
+    /**
+     * @instance Reduces the saturation of the color to make it appear duller.
+     * @param percent - The percentage to reduce saturation (0–100).
+     * @returns A new `Color` instance with the modified saturation.
+     */
+    applyDullness(percent) {
+        const [h, s, l] = _extractSolidColorValues(this.hsl);
+        const newS = Math.max(0, s - percent);
+        const newHSL = `hsl(${h}, ${newS}%, ${l}%)`;
+        return new Color(newHSL);
+    }
+    /**
+     * @instance Softens the color toward white by reducing saturation and increasing lightness based on a percentage.
+     * - *This creates a soft UI-like white shade effect (similar to some UI libraries' light color scale).*
+     * @param percent - Value from 0 to 100 representing how far to push the color toward white.
+     * @returns A new `Color` instance shifted toward white.
+     */
+    applyWhiteShade(percent) {
+        const [h, s, l] = _extractSolidColorValues(this.hsl);
+        // Cap values to avoid overshooting
+        const newS = Math.max(0, s - (s * percent) / 100);
+        const newL = Math.min(100, l + ((100 - l) * percent) / 100);
+        const newHSL = `hsl(${h}, ${newS}%, ${newL}%)`;
+        return new Color(newHSL);
+    }
+    /**
+     * @instance Blends the current color with another color based on the given weight.
+     * @param other - The color in any 6 `(Hex, Hex8 RGB, RGBA, HSL or HSLA)` to blend with.
+     * @param weight - A number from 0 to 1 indicating the weight of the other color. Defaults to `0.5`.
+     * 				 - `weight = 0` → only the original color (this)
+     *				 - `weight = 1` → only the other color
+     *				 - `weight = 0.5` → equal blend between the two
+     * @returns A new `Color` instance representing the blended result.
+     */
+    blendWith(other, weight = 0.5) {
+        const w = Math.max(0, Math.min(1, weight));
+        const converted = new Color(other);
+        const rgb1 = _extractSolidColorValues(this.rgb);
+        const rgb2 = _extractSolidColorValues(converted.rgb);
+        const blended = rgb1.map((c, i) => Math.round(c * (1 - w) + rgb2[i] * w));
+        const blendedRGB = `rgb(${blended[0]}, ${blended[1]}, ${blended[2]})`;
+        return new Color(blendedRGB);
+    }
+    /**
+     * @instance Calculates the contrast ratio between this color and another color (WCAG).
+     * @param other - The other color to compare against.
+     * @returns A number representing the contrast ratio (rounded to 2 decimal places).
+     */
+    contrastRatio(other) {
+        const newColor = new Color(other);
+        const luminance = (rgb) => {
+            const [r, g, b] = _extractSolidColorValues(rgb).map((v) => {
+                const c = v / 255;
+                return c <= 0.03928 ?
+                    c / 12.92
+                    : Math.pow((c + 0.055) / 1.055, 2.4);
+            });
+            return 0.2126 * r + 0.7152 * g + 0.0722 * b;
         };
+        const lum1 = luminance(this.rgb);
+        const lum2 = luminance(newColor.rgb);
+        const brighter = Math.max(lum1, lum2);
+        const darker = Math.min(lum1, lum2);
+        const ratio = (brighter + 0.05) / (darker + 0.05);
+        return Math.round(ratio * 100) / 100;
+    }
+    /**
+     * @instance Returns the complementary color by rotating the hue 180 degrees.
+     * @returns A new Color that is the complement of the current color.
+     */
+    getComplementaryColor() {
+        const [h, s, l] = _extractSolidColorValues(this.hsl);
+        const newHue = (h + 180) % 360;
+        const newHSL = `hsl(${newHue}, ${s}%, ${l}%)`;
+        return new Color(newHSL);
+    }
+    /**
+     * @instance Generates a color scheme of analogous colors, including the base color.
+     * Analogous colors are next to each other on the color wheel (±30°).
+     * @returns An array of three Color instances: [base, left, right].
+     */
+    getAnalogousColors() {
+        const [h, s, l] = _extractSolidColorValues(this.hsl);
+        const left = `hsl(${(h + 330) % 360}, ${s}%, ${l}%)`;
+        const right = `hsl(${(h + 30) % 360}, ${s}%, ${l}%)`;
+        return [this, new Color(left), new Color(right)];
+    }
+    /**
+     * @instance Generates a color triad scheme including the base color.
+     * Triadic colors are evenly spaced (120° apart) on the color wheel.
+     * @returns An array of three Color instances: [base, triad1, triad2].
+     */
+    getTriadColors() {
+        const [h, s, l] = _extractSolidColorValues(this.hsl);
+        const c1 = `hsl(${(h + 120) % 360}, ${s}%, ${l}%)`;
+        const c2 = `hsl(${(h + 240) % 360}, ${s}%, ${l}%)`;
+        return [this, new Color(c1), new Color(c2)];
+    }
+    /**
+     * @instance Generates a tetradic color scheme including the base color.
+     * Tetradic colors form a rectangle on the color wheel (90° apart).
+     * @returns An array of four Color instances: [base, tetrad1, tetrad2, tetrad3].
+     */
+    getTetradColors() {
+        const [h, s, l] = _extractSolidColorValues(this.hsl);
+        const c1 = `hsl(${(h + 90) % 360}, ${s}%, ${l}%)`;
+        const c2 = `hsl(${(h + 180) % 360}, ${s}%, ${l}%)`;
+        const c3 = `hsl(${(h + 270) % 360}, ${s}%, ${l}%)`;
+        return [this, new Color(c1), new Color(c2), new Color(c3)];
+    }
+    /**
+     * @instance Gets the `WCAG` accessibility rating between this and another color.
+     * @param other - The other color to test contrast against.
+     * @returns 'Fail', 'AA', or 'AAA' based on `WCAG 2.1` contrast standards.
+     */
+    getWCAGRating(other) {
+        const ratio = this.contrastRatio(other);
+        if (ratio >= 7)
+            return 'AAA';
+        if (ratio >= 4.5)
+            return 'AA';
+        return 'Fail';
+    }
+    /**
+     * @instance Determines if the color is light based on its perceived brightness.
+     * @returns `true` if light, `false` if dark.
+     */
+    isLightColor() {
+        const [r, g, b] = _extractSolidColorValues(this.rgb);
+        const brightness = (r * 299 + g * 587 + b * 114) / 1000;
+        return brightness > 127.5;
     }
     /**
      * @static Checks if a color is in `Hex6` format.
@@ -166,40 +320,40 @@ export class Color {
         return /^#[0-9A-Fa-f]{8}$/.test(color);
     }
     /**
-     * @static Checks if a color is in `RGB` format.
+     * @static Checks if a color is in `RGB` format and within valid ranges.
      *
      * @param color Color to check.
-     * @returns Boolean: `true` if it's an `RGB` color, `false` if not.
+     * @returns `true` if it's a `RGB` color, `false` if not.
      */
     static isRGB(color) {
-        return /^rgb\(\d{1,3},\s*\d{1,3},\s*\d{1,3}\)$/.test(color);
+        return _isRGB(color);
     }
     /**
-     * @static Checks if a color is in `RGBA` format.
+     * @static Checks if a color is in `RGBA` format and within valid ranges.
      *
      * @param color Color to check.
-     * @returns Boolean: `true` if it's an `RGBA` color, `false` if not.
+     * @returns `true` if it's a `RGBA` color, `false` if not.
      */
     static isRGBA(color) {
-        return /^rgba\(\d{1,3},\s*\d{1,3},\s*\d{1,3},\s*(0|1|0?\.\d+)\)$/.test(color);
+        return _isRGBA(color);
     }
     /**
-     * @static Checks if a color is in `HSL` format.
+     * @static Checks if a color is in `HSL` format and within valid ranges.
      *
      * @param color Color to check.
-     * @returns Boolean: `true` if it's an `HSL` color, `false` if not.
+     * @returns `true` if it's a `HSL` color, `false` if not.
      */
     static isHSL(color) {
-        return /^hsl\(\d{1,3},\s*\d{1,3}%,\s*\d{1,3}%\)$/.test(color);
+        return _isHSL(color);
     }
     /**
-     * @static Checks if a color is in `HSLA` format.
+     * @static Checks if a color is in `HSLA` format and within valid ranges.
      *
      * @param color Color to check.
-     * @returns Boolean: `true` if it's an `HSLA` color, `false` if not.
+     * @returns `true` if it's a `HSLA` color, `false` if not.
      */
     static isHSLA(color) {
-        return /^hsla\(\d{1,3},\s*\d{1,3}%,\s*\d{1,3}%,\s*(0|1|0?\.\d+)\)$/.test(color);
+        return _isHSLA(color);
     }
     /**
      * @private Converts the given color to all other formats while preserving the original.
@@ -234,4 +388,19 @@ export class Color {
         }
         throw new Error(`Unrecognized color format: ${color}`);
     }
+    /**
+     * @private @static Internal factory to create a Color instance from parsed parts.
+     * @param parts All the color parts as object.
+     * @returns An instance of `Color`.
+     */
+    static #fromParts(parts) {
+        const color = Object.create(Color.prototype);
+        color.hex = parts.hex;
+        color.hex8 = parts.hex8;
+        color.rgb = parts.rgb;
+        color.rgba = parts.rgba;
+        color.hsl = parts.hsl;
+        color.hsla = parts.hsla;
+        return color;
+    }
 }

package/dist/esm/colors/helpers.js

@@ -81,7 +81,7 @@ export const _extractAlphaColorValues = (colorString) => {
     return (colorString.match(/[\d.]+%?/g) || []).map((value) => parseFloat(value));
 };
 /**
- * * Checks if a color is in `Hex` format.
+ * @private Checks if a color is in `Hex` format.
  *
  * @param color Color to check.
  * @returns Boolean: `true` if it's a `Hex` color, `false` if not.
@@ -90,58 +90,92 @@ export function _isHex6(color) {
     return /^#[0-9A-Fa-f]{6}$/.test(color);
 }
 /**
- * * Checks if a color is in `RGB` format.
+ * @private Checks if a color is in `Hex8` format.
  *
  * @param color Color to check.
- * @returns Boolean: `true` if it's an `RGB` color, `false` if not.
+ * @returns Boolean: `true` if it's a `Hex8` color, `false` if not.
  */
-export function _isRGB(color) {
-    return /^rgb\(\d{1,3},\s*\d{1,3},\s*\d{1,3}\)$/.test(color);
+export function _isHex8(color) {
+    return /^#[0-9A-Fa-f]{8}$/.test(color);
 }
 /**
- * * Checks if a color is in `HSL` format.
+ * @private Checks if a color is in `RGB` format and within valid ranges.
  *
  * @param color Color to check.
- * @returns Boolean: `true` if it's an `HSL` color, `false` if not.
+ * @returns `true` if it's a `RGB` color, `false` if not.
  */
-export function _isHSL(color) {
-    return /^hsl\(\d{1,3},\s*\d{1,3}%,\s*\d{1,3}%\)$/.test(color);
+export function _isRGB(color) {
+    const match = color.match(/^rgb\(\s*(\d{1,3}(?:\.\d+)?),\s*(\d{1,3}(?:\.\d+)?),\s*(\d{1,3}(?:\.\d+)?)\s*\)$/);
+    if (!match)
+        return false;
+    const [r, g, b] = match.slice(1).map(Number);
+    return (_isValidRGBComponent(r) &&
+        _isValidRGBComponent(g) &&
+        _isValidRGBComponent(b));
 }
 /**
- * @static
- * Checks if a color is in `Hex8` format.
+ * @private Checks if a color is in `RGBA` format and within valid ranges.
  *
  * @param color Color to check.
- * @returns Boolean: `true` if it's a `Hex8` color, `false` if not.
+ * @returns `true` if it's a `RGBA` color, `false` if not.
  */
-export function _isHex8(color) {
-    return /^#[0-9A-Fa-f]{8}$/.test(color);
+export function _isRGBA(color) {
+    const match = color.match(/^rgba\(\s*(\d{1,3}(?:\.\d+)?),\s*(\d{1,3}(?:\.\d+)?),\s*(\d{1,3}(?:\.\d+)?),\s*(0|1|0?\.\d+)\s*\)$/);
+    if (!match)
+        return false;
+    const [r, g, b, a] = match.slice(1).map(Number);
+    return (_isValidRGBComponent(r) &&
+        _isValidRGBComponent(g) &&
+        _isValidRGBComponent(b) &&
+        _isValidAlpha(a));
 }
 /**
- * @static
- * Checks if a color is in `RGBA` format.
+ * @private Checks if a color is in `HSL` format and within valid ranges.
  *
  * @param color Color to check.
- * @returns Boolean: `true` if it's an `RGBA` color, `false` if not.
+ * @returns `true` if it's a `HSL` color, `false` if not.
  */
-export function _isRGBA(color) {
-    return /^rgba\(\d{1,3},\s*\d{1,3},\s*\d{1,3},\s*(0|1|0?\.\d+)\)$/.test(color);
+export function _isHSL(color) {
+    const match = color.match(/^hsl\(\s*(\d{1,3}(?:\.\d+)?),\s*(\d{1,3}(?:\.\d+)?)%,\s*(\d{1,3}(?:\.\d+)?)%\s*\)$/);
+    if (!match)
+        return false;
+    const [h, s, l] = match.slice(1).map(Number);
+    return _isValidHue(h) && _isValidPercentage(s) && _isValidPercentage(l);
 }
 /**
- * @static
- * Checks if a color is in `HSLA` format.
+ * @private Checks if a color is in `HSLA` format and within valid ranges.
  *
  * @param color Color to check.
- * @returns Boolean: `true` if it's an `HSLA` color, `false` if not.
+ * @returns `true` if it's a `HSLA` color, `false` if not.
  */
 export function _isHSLA(color) {
-    return /^hsla\(\d{1,3},\s*\d{1,3}%,\s*\d{1,3}%,\s*(0|1|0?\.\d+)\)$/.test(color);
+    const match = color.match(/^hsla\(\s*(\d{1,3}(?:\.\d+)?),\s*(\d{1,3}(?:\.\d+)?)%,\s*(\d{1,3}(?:\.\d+)?)%,\s*(0|1|0?\.\d+)\s*\)$/);
+    if (!match)
+        return false;
+    const [h, s, l, a] = match.slice(1).map(Number);
+    return (_isValidHue(h) &&
+        _isValidPercentage(s) &&
+        _isValidPercentage(l) &&
+        _isValidAlpha(a));
 }
 /**
- * * Type guard to validate alpha value.
+ * @private Checks if a number is valid alpha value.
+ *
  * @param value Alpha value to check.
- * @returns Boolean: `true` if it's a valid alpha value, `false` if not.
+ * @returns `true` if it's a valid alpha value, `false` if not.
  */
 export function _isValidAlpha(value) {
     return value >= 0 && value <= 1 && !isNaN(value);
 }
+/** * @private Validates RGB component (0–255). */
+export function _isValidRGBComponent(value) {
+    return value >= 0 && value <= 255;
+}
+/** * @private Validates HSL hue (0–360). */
+export function _isValidHue(value) {
+    return value >= 0 && value <= 360;
+}
+/** * @private Validates HSL percentage components (0–100). */
+export function _isValidPercentage(value) {
+    return value >= 0 && value <= 100;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nhb-toolbox",
-  "version": "4.0.36",
+  "version": "4.0.40",
   "description": "A versatile collection of smart, efficient, and reusable utility functions for everyday development needs.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",