/** * 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 Branded, bn as Percent, vn as NumberRange, y as Maybe } from "./index-Dx3yeNwR.mjs"; import { t as CSS_COLORS } from "./css-colors-Dqz6Bfnp.mjs"; //#region src/types/colors.d.ts /** - A string, number for generating color. */ type ColorInput = string | number; /** - An array of strings/numbers or nested arrays of strings/numbers for generating colors. */ type ColorInputArray = Array; /** * * Represents a hexadecimal color code. * * Format: `#3C6945` */ type Hex = `#${string}`; /** * * Represents a hexadecimal color code. * * Format: `#3C6945` */ type Hex6 = Branded; /** * * Represents an RGB color string. * * Format: `rgb(R, G, B)` * * - R (Red): 0-255 * - G (Green): 0-255 * - B (Blue): 0-255 */ type RGB = `rgb(${number}, ${number}, ${number})` | `rgb(${number},${number},${number})`; /** * * Represents an HSL color string. * * Format: `hsl(H, S%, L%)` * * - H (Hue): 0-360 * - S (Saturation): 0-100% * - L (Lightness): 0-100% */ type HSL = `hsl(${number}, ${number}%, ${number}%)` | `hsl(${number},${number}%,${number}%)`; /** * * Represents a hexadecimal color code with optional alpha channel. * * Format: `#3C6945FF` */ type Hex8 = Branded; /** * * Represents an RGBA color string, now includes optional alpha (opacity). * * Format: `rgba(R, G, B, A)` */ type RGBA = `rgba(${number}, ${number}, ${number}, ${number})` | `rgba(${number},${number},${number},${number})`; /** * * Represents an HSLA color string with optional alpha channel. * * Format: `hsla(H, S%, L%, A)` */ type HSLA = `hsla(${number}, ${number}%, ${number}%, ${number})` | `hsla(${number},${number}%,${number}%,${number})`; /** Basic color type: `hex`, `rgb` or `hsl`. */ type $ColorType = 'hex' | 'rgb' | 'hsl'; /** Options for random color generation. */ interface RandomColorOptions { /** The type of expected return type of color: `hex`, `rgb` or `hsl`. Default is `'hex'`. */ colorType?: C | $ColorType; /** The maximum number of recent colors to store in memory. Default is `16`. */ maxColors?: number; } /** Infers random color type (`Hex6`, `RGB`, or `HSL`) based on the provided color type `C`. */ type RandomColor = undefined> = C extends undefined | 'hex' ? Hex6 : C extends 'hsl' ? HSL : C extends 'rgb' ? RGB : Hex6; /** * Union type representing a color in Hex6, RGB, or HSL format. */ type ColorTypeSolid = Hex6 | RGB | HSL; /** * Union type representing a color in Hex8, RGBA, or HSLA format. */ type ColorTypeAlpha = Hex8 | RGBA | HSLA; /** * Union of Alpha & Solid `Hex`, `RGB` and `HSL` */ type ColorType = Hex | Hex6 | RGB | HSL | Hex8 | RGBA | HSLA; /** - Colors Object that includes `Hex8`, `RGBA` and `HSLA` formats of the same color. */ interface SolidColors { /** Represents a normal Hex color */ hex: Hex6; /** Represents a normal RGB color */ rgb: RGB; /** Represents a normal HSL color */ hsl: HSL; } /** - Colors Object that includes `Hex`, `RGB` and `HSL` formats of the same color. */ interface AlphaColors { /** Represents a Hex color with alpha channel */ hex8: Hex8; /** Represents a RGBA color with alpha channel */ rgba: RGBA; /** Represents a HSLA color with alpha channel */ hsla: HSLA; } /** * Represents a tuple of three numerical values corresponding to RGB or HSL color components. */ type SolidValues = [number, number, number]; /** * Represents a tuple of four numerical values corresponding to RGBA or HSLA color components. */ type AlphaValues = [number, number, number, number]; /** * * Represents the converted color formats for a given color type. * * - If the input is `Hex`, the output includes `RGB` and `HSL`. * - If the input is `RGB`, the output includes `Hex` and `HSL`. * - If the input is `HSL`, the output includes `Hex` and `RGB`. */ interface ConvertedColors extends Record { /** - The Hex representation (excluded if the input is already Hex). */ hex: T extends Hex6 | ColorTypeAlpha ? never : Hex6; /** - The RGB representation (excluded if the input is already RGB). */ rgb: T extends RGB | ColorTypeAlpha ? never : RGB; /** - The HSL representation (excluded if the input is already HSL). */ hsl: T extends HSL | ColorTypeAlpha ? never : HSL; /** - The Hex8 representation with opacity (excluded if the input is already Hex8). */ hex8: T extends Hex8 | ColorTypeSolid ? never : Hex8; /** - The RGBA representation (excluded if the input is already RGBA). */ rgba: T extends RGBA | ColorTypeSolid ? never : RGBA; /** - The HSLA representation (excluded if the input is already HSLA). */ hsla: T extends HSLA | ColorTypeSolid ? never : HSLA; } /** Represents an alpha value between 0 and 1 */ type AlphaValue = Branded; /** An Object representing all the colors from `Color` constructor. */ 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; } /** Analogous colors */ type Analogous = [Color, Color, Color]; /** Triad color */ type Triad = [Color, Color, Color]; /** Tetrad color */ type Tetrad = [Color, Color, Color, Color]; /** CSS named color, also includes different response colors */ type CSSColor = keyof typeof CSS_COLORS; //#endregion //#region src/colors/Color.d.ts /** * @class Represents a color in {@link Hex6 Hex}, {@link Hex8}, {@link RGB}, {@link RGBA}, {@link HSL}, and {@link HSLA} formats. * * @remarks * - Instance methods allow transforming, adjusting, and deriving new colors. * - Static methods provide format validation and type-guard–style checks for supported color representations. * * @property `hex` - {@link Hex6 Hex} color representation (without alpha). * @property `hex8` - {@link Hex8} color representation including alpha. * @property `rgb` - {@link RGB} color representation (without alpha). * @property `rgba` - {@link RGBA} color representation including alpha. * @property `hsl` - {@link HSL} color representation (without alpha). * @property `hsla` - {@link HSLA} color representation including alpha. */ declare class Color { #private; /** {@link Hex6 Hex} color representation (without alpha). */ readonly hex: Hex6; /** {@link Hex8} color representation including alpha. */ readonly hex8: Hex8; /** {@link RGB} color representation (without alpha). */ readonly rgb: RGB; /** {@link RGBA} color representation including alpha. */ readonly rgba: RGBA; /** {@link HSL} color representation (without alpha). */ readonly hsl: HSL; /** {@link HSLA} color representation including alpha. */ readonly hsla: HSLA; /** * * Creates a new `Color` instance with a random color and automatically converts the generated color to all other supported formats: {@link Hex6 Hex}, {@link Hex8}, {@link RGB}, {@link RGBA}, {@link HSL}, and {@link HSLA}. * * @description * The `Color` class generates a random color in six common color representations: * - {@link Hex6 Hex} (e.g., `#ff5733`) * - {@link Hex8} (Hex with opacity, e.g., `#ff573380`) * - {@link RGB} (e.g., `rgb(255, 87, 51)`) * - {@link RGBA} (e.g., `rgba(255, 87, 51, 1)`) * - {@link HSL} (e.g., `hsl(14, 100%, 60%)`) * - {@link HSLA} (e.g., `hsla(14, 100%, 60%, 1)`) * * @remarks * - Instance methods allow transforming, adjusting, and deriving new colors. * - Static methods provide format validation and type-guard–style checks for supported color representations. * * @example * // Generate a random color * const randomColor = new Color(); * console.log(randomColor.hex, randomColor.rgb, randomColor.hsl); * * @returns Instance of `Color`. */ constructor(); /** * * Creates a new `Color` instance with the input color and automatically converts it to all other supported formats: {@link Hex6 Hex}, {@link Hex8}, {@link RGB}, {@link RGBA}, {@link HSL}, and {@link HSLA}. * * @description * The `Color` class allows seamless transformation between six common color representations: * - {@link Hex6 Hex} (e.g., `#ff5733`) * - {@link Hex8} (Hex with opacity, e.g., `#ff573380`) * - {@link RGB} (e.g., `rgb(255, 87, 51)`) * - {@link RGBA} (e.g., `rgba(255, 87, 51, 1)`) * - {@link HSL} (e.g., `hsl(14, 100%, 60%)`) * - {@link HSLA} (e.g., `hsla(14, 100%, 60%, 1)`) * * You can create a color from any of these formats, and the class will populate the rest. * * @remarks * - Instance methods allow transforming, adjusting, and deriving new colors. * - Static methods provide format validation and type-guard–style checks for supported color representations. * * @param color - A color string in any supported format (`Hex`, `Hex8`, `RGB`, `RGBA`, `HSL`, or `HSLA`) to convert in all other formats (includes the current format). * * @example * // Convert an existing Hex color to all other formats * const color = new Color("#ff5733"); * console.log(color.rgb); // 'rgb(255, 87, 51)' * console.log(color.hsl); // 'hsl(14, 100%, 60%)' * console.log(color.rgba); // 'rgba(255, 87, 51, 1)' * console.log(color.hsla); // 'hsla(14, 100%, 60%, 1)' * console.log(color.hex8); // '#FF5733FF' * * @example * // Handle a color with alpha * const alphaColor = new Color("rgba(255, 0, 0, 0.5)"); * console.log(alphaColor.hex8); // '#FF000080' * console.log(alphaColor.hsla); // 'hsla(0, 100%, 50%, 0.5)' * * @returns Instance of `Color`. */ constructor(color: ColorType); /** * * Creates a new `Color` instance using a standard (CSS) named color and automatically converts it to all other supported formats: {@link Hex6 Hex}, {@link Hex8}, {@link RGB}, {@link RGBA}, {@link HSL}, and {@link HSLA}. * * @description * This allows you to use any valid named color from standard `150+` CSS color names (e.g., `"red"`, `"blue"`, `"rebeccapurple"`) * * @param color - A named color string from standard `150+` CSS color names ({@link CSSColor}). * * @remarks * - Instance methods allow transforming, adjusting, and deriving new colors. * - Static methods provide format validation and type-guard–style checks for supported color representations. * * @example * // Using a CSS named color * const sky = new Color("skyblue"); * console.log(sky.hex); // '#87CEEB' * console.log(sky.rgba); // 'rgba(135, 206, 235, 1)' * * @returns Instance of `Color`. */ constructor(color: CSSColor); /** * * Creates a new `Color` instance and automatically converts the input color to all other supported formats: {@link Hex6 Hex}, {@link Hex8}, {@link RGB}, {@link RGBA}, {@link HSL}, and {@link HSLA}. * * @description * The `Color` class allows seamless transformation between six common color representations: * - {@link Hex6 Hex} (e.g., `#ff5733`) * - {@link Hex8} (Hex with opacity, e.g., `#ff573380`) * - {@link RGB} (e.g., `rgb(255, 87, 51)`) * - {@link RGBA} (e.g., `rgba(255, 87, 51, 1)`) * - {@link HSL} (e.g., `hsl(14, 100%, 60%)`) * - {@link HSLA} (e.g., `hsla(14, 100%, 60%, 1)`) * * You can create a color from any of these formats, and the class will populate the rest. * If no color is passed, a random color will be generated. * * @remarks * - Instance methods allow transforming, adjusting, and deriving new colors. * - Static methods provide format validation and type-guard–style checks for supported color representations. * * @param color - An optional input color string in any supported format (`Hex`, `Hex8`, `RGB`, `RGBA`, `HSL`, or `HSLA`) or a named color string from standard `150+` CSS color names ({@link CSSColor}) to convert in all other (includes the current format) formats. * * @example * // Convert an existing Hex color to all other formats * const color = new Color("#ff5733"); * console.log(color.rgb); // 'rgb(255, 87, 51)' * console.log(color.hsl); // 'hsl(14, 100%, 60%)' * console.log(color.rgba); // 'rgba(255, 87, 51, 1)' * console.log(color.hsla); // 'hsla(14, 100%, 60%, 1)' * console.log(color.hex8); // '#FF5733FF' * * @example * // Handle a color with alpha * const alphaColor = new Color("rgba(255, 0, 0, 0.5)"); * console.log(alphaColor.hex8); // '#FF000080' * console.log(alphaColor.hsla); // 'hsla(0, 100%, 50%, 0.5)' * * @example * // Generate a random color * const randomColor = new Color(); * console.log(randomColor.hex, randomColor.rgb, randomColor.hsl); * * @example * // Using a CSS named color * const sky = new Color("skyblue"); * console.log(sky.hex); // '#87CEEB' * console.log(sky.rgba); // 'rgba(135, 206, 235, 1)' * * @returns Instance of `Color`. */ constructor(color?: ColorType | CSSColor); /** Iterates over the color representations (`Hex`, `RGB`, `HSL`). */ [Symbol.iterator](): Generator; /** * Allows the color to be used in string and number contexts. * @param hint The hint to determine the conversion type. */ [Symbol.toPrimitive](hint: string): number | this | Hex8; /** * @instance Sets the opacity of this color to the given **absolute** percentage and returns a new instance. * * @remarks * - This is an **absolute setter**: passing `50` means "set opacity to exactly 50%", regardless of the current opacity. * - For solid colors ({@link Hex6}/{@link RGB}/{@link HSL}): Adds an alpha channel with the specified opacity. * - For alpha colors ({@link Hex8}/{@link RGBA}/{@link HSLA}): Replaces the existing alpha channel. * * @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"); * const alpha50 = color.applyOpacity(50); // 50% opacity * console.log(alpha50.rgba); // rgba(255, 0, 0, 0.5) * * @example * const alphaColor = new Color("#ff000080"); // Color with 50% opacity * const alpha75 = alphaColor.applyOpacity(75); // Change to 75% opacity * console.log(alpha75.hex8); // #FF0000BF */ applyOpacity(opacity: Percent): Color; /** * @instance Darkens the color by **subtracting** the given percentage points from the current lightness in HSL space. * * @remarks * - This is a **relative adjustment**: passing `20` means "reduce lightness by 20 percentage points" from its current value. * - Lightness is clamped to `0%` at minimum. * - The original alpha (opacity) is preserved in the returned color. * * @param percent - The percentage points to subtract from lightness (`0–100`). * @returns A new `Color` instance with the reduced lightness. * * @example * const blue = new Color("#0000ff"); // hsl(240, 100%, 50%) * const darkerBlue = blue.applyDarkness(20); * console.log(darkerBlue.hsl); // hsl(240, 100%, 30%) */ applyDarkness(percent: Percent): Color; /** * @instance Lightens the color by **adding** the given percentage points to the current lightness in HSL space. * * @remarks * - This is a **relative adjustment**: passing `30` means "increase lightness by 30 percentage points" from its current value. * - Lightness is clamped to `100%` at maximum. * - The original alpha (opacity) is preserved in the returned color. * * @param percent - The percentage points to add to lightness (`0–100`). * @returns A new `Color` instance with the increased lightness. * * @example * const green = new Color("#008000"); // hsl(120, 100%, 25.1%) * const lighterGreen = green.applyBrightness(30); * console.log(lighterGreen.hsl); // hsl(120, 100%, 55.1%) */ applyBrightness(percent: Percent): Color; /** * @instance Desaturates the color by **subtracting** the given percentage points from the current saturation in HSL space. * * @remarks * - This is a **relative adjustment**: passing `50` means "reduce saturation by 50 percentage points" from its current value. * - Saturation is clamped to `0%` at minimum (fully desaturated / grayscale). * - The original alpha (opacity) is preserved in the returned color. * * @param percent - The percentage points to subtract from saturation (`0–100`). * @returns A new `Color` instance with the reduced saturation. * * @example * const pink = new Color("#ff69b4"); // hsl(330, 100%, 70.59%) * const dullPink = pink.applyDullness(50); * console.log(dullPink.hsl); // hsl(330, 50%, 70.59%) */ applyDullness(percent: Percent): Color; /** * @instance Softens the color toward white by **proportionally** reducing saturation and increasing lightness. * * @remarks * - This is a **proportional blend**: passing `40` means "move 40% of the *remaining distance* toward pure white". * - Unlike {@link applyBrightness} or {@link applyDullness}, the effect scales relative to the current distance from white, producing a natural pastel/tint effect. * - This creates a soft UI-like white shade effect (similar to some UI libraries' light color scale). * - The original alpha (opacity) is preserved in the returned color. * * @param percent - Value from `0` to `100` representing how far to push the color toward white. * @returns A new `Color` instance shifted toward white. * * @example * const purple = new Color("#800080"); // hsl(300, 100%, 25.1%) * const softPurple = purple.applyWhiteShade(40); * console.log(softPurple.hsl); // hsl(300, 60%, 55.06%) */ applyWhiteShade(percent: Percent): Color; /** * @instance Blends the current color with another color based on the given weight. * * @remarks * If any of the input colors has opacity (alpha channel), it might be lost or distorted from the generated alpha variants of the respective color formats. * * @param other - The color in any of 6 ({@link Hex6 Hex}, {@link Hex8}, {@link RGB}, {@link RGBA}, {@link HSL} or {@link HSLA}) formats or a {@link CSSColor} 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. * - `weight = 1` → only the other color. * - `weight = 0.5` → equal blend between the two. * @returns A new `Color` instance representing the blended result, with proper alpha blending. */ blendWith(other: ColorType | CSSColor, 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 | CSSColor): 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. * * @remarks * Analogous colors are next to each other on the color wheel (±30°). * * @returns An array of three `Color` instances: `[base, left, right]`. */ getAnalogousColors(): Analogous; /** * @instance Generates a color triad scheme including the base color. * * @remarks * Triadic colors are evenly spaced (120° apart) on the color wheel. * * @returns An array of three `Color` instances: `[base, triad1, triad2]`. */ getTriadColors(): Triad; /** * @instance Generates a tetradic color scheme including the base color. * * @remarks * Tetradic colors form a rectangle on the color wheel (90° apart). * * @returns An array of four `Color` instances: `[base, tetrad1, tetrad2, tetrad3]`. */ getTetradColors(): Tetrad; /** * @instance Generates a color palette of evenly distributed hues based on the current color's saturation, lightness, and alpha. * * @remarks * - Colors are spaced evenly around the color wheel (`360° / count` apart), starting from the current hue. * - Saturation, lightness, and alpha from the source color are preserved across all generated colors. * * @typeParam N - A literal number type representing the palette size. * @param count - The number of colors to generate in the palette (must be a positive integer ≥ `1`). Default: `7`. * @param step - The step value (degree) to be added to the hue of the previous color. Default: `360 / count`. * @returns Array of `Color` instances with the specified count. * * @example * const red = new Color("#ff0000"); * const palette = red.generatePalette(4); * console.log(palette.map((color) => color.hex)); * // ['#FF0000', '#80FF00', '#00FFFF', '#8000FF'] */ generatePalette(count?: NumberRange<1, 360>, step?: NumberRange<1, 360>): Array; /** * @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 | CSSColor): 'Fail' | 'AA' | 'AAA'; /** * @instance Determines if the color is light based on its perceived brightness. * @param threshold Optional brightness threshold (`0–255`). Defaults to `127.5`. * @remarks The brightness {@link threshold} is clamped to the valid *RGB range* (`0–255`) to prevent invalid comparisons. * @returns `true` if light, `false` if dark. */ isLightColor(threshold?: number): boolean; /** * @instance Convert the color to string. * @returns The `Hex8` representation of the color. * * @remarks * - Called by `String()`, `Object.prototype.toString()` or in template literals. * - Uses the same implementation as `toJSON()`. */ toString(): Hex8; /** * @instance Convert the color to JSON. * @returns The `Hex8` representation of the color. * * @remarks * - Called by `JSON.stringify()`. * - It uses the same implementation as `toString()`. */ toJSON(): Hex8; /** * @static Checks if a color is in {@link Hex6} format. * * @param color Color to check. * @returns Boolean: `true` if it's a {@link Hex6} color, `false` if not. */ static isHex6(color: string): color is Hex6; /** * @static Checks if a color is in {@link Hex8} format. * * @param color Color to check. * @returns Boolean: `true` if it's a {@link Hex8} color, `false` if not. */ static isHex8(color: string): color is Hex8; /** * @static Checks if a color is in {@link RGB} format and within valid ranges. * * @param color Color to check. * @returns `true` if it's a {@link RGB} color, `false` if not. */ static isRGB(color: string): color is RGB; /** * @static Checks if a color is in {@link RGBA} format and within valid ranges. * * @param color Color to check. * @returns `true` if it's a {@link RGBA} color, `false` if not. */ static isRGBA(color: string): color is RGBA; /** * @static Checks if a color is in {@link HSL} format and within valid ranges. * * @param color Color to check. * @returns `true` if it's a {@link HSL} color, `false` if not. */ static isHSL(color: string): color is HSL; /** * @static Checks if a color is in {@link HSLA} format and within valid ranges. * * @param color Color to check. * @returns `true` if it's a {@link HSLA} color, `false` if not. */ static isHSLA(color: string): color is HSLA; /** * @static Checks if a color is a valid CSS color name ({@link CSSColor}). * * @remarks * - This method checks against a predefined list of CSS color names. * - It does not validate format types like `Hex`, `RGB`, or `HSL` or their alpha channels. * * @param color - The color to check. * @returns `true` if the color is a valid CSS color name, `false` otherwise. */ static isCSSColor(color: string): color is CSSColor; } //#endregion export { RandomColorOptions as C, Triad as D, Tetrad as E, RandomColor as S, SolidValues as T, Hex as _, AlphaValues as a, RGB as b, ColorInput as c, ColorTypeAlpha as d, ColorTypeSolid as f, HSLA as g, HSL as h, AlphaValue as i, ColorInputArray as l, ConvertedColors as m, $ColorType as n, Analogous as o, Colors as p, AlphaColors as r, CSSColor as s, Color as t, ColorType as u, Hex6 as v, SolidColors as w, RGBA as x, Hex8 as y };