nhb-toolbox

import type { Percent } from '../number/types'; import type { Analogous, ColorType, CSSColor, Hex6, Hex8, HSL, HSLA, RGB, RGBA, Tetrad, Triad } from './types'; /** * @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. */ export 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<HSL | HSLA | RGB | RGBA | Hex6 | Hex8, void, unknown>; /** * 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 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; /** * @instance Applies or modifies the opacity of a color and returns a new instance. * * @remarks * - 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}): Updates 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 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. * * @remarks * 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. * * @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 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; /** * @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; } export { Color as Colour };