toolbox-x 1.0.0

package/dist/Color-D38Xrw65.d.mts

@@ -0,0 +1,486 @@
+/**
+ * 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 { $ as Maybe, V as Branded, rn as Percent } from "./object-B0TV3eHx.mjs";
+import { t as CSS_COLORS } from "./css-colors-CXTp1vvy.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<ColorInput | ColorInputArray>;
+/**
+ * * Represents a hexadecimal color code.
+ * * Format: `#3C6945`
+ */
+type Hex = `#${string}`;
+/**
+ * * Represents a hexadecimal color code.
+ * * Format: `#3C6945`
+ */
+type Hex6 = Branded<Hex, 'Hex6'>;
+/**
+ * * 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<Hex, 'Hex8'>;
+/**
+ * * 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})`;
+/** Represents an object with `hex` (`hex6`) and `rgb` color */
+type RandomHexRGB = {
+  /** Represents a hexadecimal color code. */hex: Hex6; /** Represents an RGB color string. */
+  rgb: RGB;
+};
+/** Basic color type: `hex`, `rgb` or `hsl`. */
+type $ColorType = 'hex' | 'rgb' | 'hsl';
+/** Options for random color generation. */
+interface RandomColorOptions<C extends $ColorType> {
+  /** 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<C extends Maybe<$ColorType> = 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<T extends ColorType> extends Record<string, ColorType> {
+  /** - 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<number, 'AlphaValue'>;
+/** 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;
+  readonly hex: Hex6;
+  readonly hex8: Hex8;
+  readonly rgb: RGB;
+  readonly rgba: RGBA;
+  readonly hsl: HSL;
+  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<Hex6 | Hex8 | RGB | RGBA | HSL | HSLA, void, unknown>;
+  /**
+   * @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;
+}
+//#endregion
+export { RandomColorOptions as C, Tetrad as D, SolidValues as E, Triad as O, RandomColor as S, SolidColors 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, RandomHexRGB as w, RGBA as x, Hex8 as y };