nhb-toolbox/dist/dts/colors/utils.d.ts

A versatile collection of smart, efficient, and reusable utility functions, classes and types for everyday development needs.

import type { Percent } from '../number/types';
import type { AlphaValues, Hex, Hex8, HSL, HSLA, RGB, RGBA, SolidValues } from './types';
/**
 * * Extracts numbers from a color string like `rgb(66, 103, 69)` or `hsl(120, 42.86%, 41.18%)`.
 * * Converts percentage values to decimal (e.g., `42.86%` → `42.86`).
 *
 * @param color The color string in RGB or HSL format.
 * @returns A tuple of 3 extracted numbers. `[number, number, number]`
 *
 * @remarks If the input color is not in `HSL` or `RGB` format, it will return `[0, 0, 0]`
 */
export declare function extractSolidColorValues(color: HSL | RGB): SolidValues;
/**
 * * Extracts numbers from a color string like `rgba(66, 103, 69, 0.6)` or `hsla(120, 42.86%, 41.18%, 0.9)`.
 * * Converts percentage values to decimal (e.g., `42.86%` → `42.86`).
 *
 * @param color The color string in RGBA or HSLA format.
 * @returns A tuple of 4 extracted numbers. `[number, number, number, number]`
 *
 * @remarks If the input color is not in `HSLA` or `RGBA` format, it will return `[0, 0, 0, 0]`
 */
export declare function extractAlphaColorValues(color: HSLA | RGBA): AlphaValues;
/**
 * * Converts percentage (0-100) to a 2-digit hex string.
 *
 * @param percent - The percentage (0-100) value.
 * @returns A 2-digit hex string representing the percentage (0-100) value.
 *
 * @remarks
 * - This function ensures that the percentage value is clamped between 0 and 100, converts it to a value between 0 and 255, and then formats it as a 2-digit hexadecimal string.
 * - The resulting hex string is in uppercase for consistency with common hex color formats.
 *
 * @example
 * percentToHex(0);    // Returns "00"
 * percentToHex(50);   // Returns "7F"
 * percentToHex(100);  // Returns "FF"
 * percentToHex(150);  // Returns "FF" (ts compiler error and clamped to 100)
 * percentToHex(-20);  // Returns "00" (ts compiler error and clamped to 0)
 */
export declare function percentToHex(percent: Percent): string;
/**
 * * Applies an opacity value to a hex color string.
 *
 * @param color - The hex color string in the format `#RRGGBB` or `#RRGGBBAA`.
 * @param opacity - The opacity value as a percentage (0-100).
 * @returns The hex color string with the applied opacity in `#RRGGBBAA` format.
 *
 * @throws - {@link TypeError} If the provided color is not a valid hex color string.
 *
 * @remarks
 * - If the input color is in `#RRGGBB` format, the function will append the opacity value to create a `#RRGGBBAA` string.
 * - If the input color is already in `#RRGGBBAA` format, it will replace the existing alpha value with the new one.
 * - The function validates that the input color is a valid hex color string and that the opacity value is a valid percentage before applying the opacity.
 * - If the opacity value is invalid, it defaults to 100% opacity (i.e., "FF").
 * - The resulting hex color string is in uppercase for consistency with common hex color formats.
 *
 * @example
 * applyOpacityToHex("#FF5733", 50);   // Returns "#FF573380"
 * applyOpacityToHex("#FF573380", 25);   // Returns "#FF573340"
 */
export declare function applyOpacityToHex(color: Hex, opacity: Percent): Hex8;
/**
 * * Applies an opacity value to a hex color string.
 *
 * @param color - The hex color string in the format `#RRGGBB` or `#RRGGBBAA`.
 * @param opacity - The opacity value as a 2-digit hex string.
 * @returns The hex color string with the applied opacity in `#RRGGBBAA` format.
 *
 * @throws - {@link TypeError} If the provided color is not a valid hex color string.
 *
 * @remarks
 * - If the input color is in `#RRGGBB` format, the function will append the opacity value to create a `#RRGGBBAA` string.
 * - If the input color is already in `#RRGGBBAA` format, it will replace the existing alpha value with the new one.
 * - The function validates that the input color is a valid hex color string and that the opacity value is a valid a 2-digit hex string before applying the opacity.
 * - If the opacity value is invalid, it defaults to 100% opacity (i.e., "FF").
 * - The resulting hex color string is in uppercase for consistency with common hex color formats.
 *
 * @example
 * applyOpacityToHex("#FF5733", "80"); // Returns "#FF573380"
 * applyOpacityToHex("#FF573380", "40"); // Returns "#FF573340"
 */
export declare function applyOpacityToHex(color: Hex, opacity: string): Hex8;