@nemigo/helpers 0.13.3 → 1.5.0

package/dist/colors.d.ts

@@ -1,539 +0,0 @@
-/**
- * RGB цвет (красный, зелёный, синий)
- */
-export interface RGB {
-    /**
-     * Красный канал (0-255)
-     */
-    r: number;
-    /**
-     * Зелёный канал (0-255)
-     */
-    g: number;
-    /**
-     * Синий канал (0-255)
-     */
-    b: number;
-}
-/**
- * RGBA цвет (красный, зелёный, синий, альфа)
- */
-export interface RGBA extends RGB {
-    /**
-     * Прозрачность (0-1)
-     */
-    a: number;
-}
-/**
- * HSL цвет (оттенок, насыщенность, яркость)
- */
-export interface HSL {
-    /**
-     * Оттенок (0-360)
-     */
-    h: number;
-    /**
-     * Насыщенность (0-100)
-     */
-    s: number;
-    /**
-     * Яркость (0-100)
-     */
-    l: number;
-}
-/**
- * HSLA цвет (оттенок, насыщенность, яркость, альфа)
- */
-export interface HSLA extends HSL {
-    /**
-     * Прозрачность (0-1)
-     */
-    a: number;
-}
-/**
- * HSV цвет (оттенок, насыщенность, значение)
- */
-export interface HSV {
-    /**
-     * Оттенок (0-360)
-     */
-    h: number;
-    /**
-     * Насыщенность (0-100)
-     */
-    s: number;
-    /**
-     * Значение (0-100)
-     */
-    v: number;
-}
-/**
- * HSVA цвет (оттенок, насыщенность, значение, альфа)
- */
-export interface HSVA extends HSV {
-    /**
-     * Прозрачность (0-1)
-     */
-    a: number;
-}
-/**
- * HEX цвет в формате "#RRGGBB"
- */
-export type HEX = string;
-/**
- * HEXA цвет в формате "#RRGGBBAA"
- */
-export type HEXA = string;
-/**
- * Ограничивает значение RGB-канала в диапазоне 0-255
- */
-export declare const clampRgb: (value: number) => number;
-/**
- * Ограничивает оттенок в диапазоне 0-360
- */
-export declare const clampHue: (value: number) => number;
-/**
- * Ограничивает процентное значение в диапазоне 0-100
- */
-export declare const clampPercent: (value: number) => number;
-/**
- * Ограничивает значение альфа-канала в диапазоне 0-1
- */
-export declare const clampAlpha: (value: number) => number;
-/**
- * Парсит HEX-строку в RGB или RGBA
- *
- * Поддерживаемые форматы:
- * - #RGB
- * - #RRGGBB
- * - #RGBA
- * - #RRGGBBAA
- *
- * @param hex - HEX-строка цвета
- * @returns RGB или RGBA объект, или null если формат неверен
- *
- * @example
- * ```typescript
- * parseHex("#ff0000"); // { r: 255, g: 0, b: 0 }
- * parseHex("#f00"); // { r: 255, g: 0, b: 0 }
- * parseHex("#ff0000ff"); // { r: 255, g: 0, b: 0, a: 1 }
- * parseHex("#f00f"); // { r: 255, g: 0, b: 0, a: 1 }
- * parseHex("invalid"); // null
- * ```
- */
-export declare const parseHex: (hex: string) => RGB | RGBA | null;
-/**
- * Парсит RGB/RGBA строку в объект
- *
- * Поддерживаемые форматы:
- * - rgb(r, g, b)
- * - rgba(r, g, b, a)
- * - rgb(r g b)
- * - rgba(r g b / a)
- *
- * @param rgb - RGB/RGBA строка
- * @returns RGB или RGBA объект, или null если формат неверен
- *
- * @example
- * ```typescript
- * parseRgb("rgb(255, 0, 0)"); // { r: 255, g: 0, b: 0 }
- * parseRgb("rgba(255, 0, 0, 0.5)"); // { r: 255, g: 0, b: 0, a: 0.5 }
- * parseRgb("rgb(255 0 0)"); // { r: 255, g: 0, b: 0 }
- * parseRgb("rgba(255 0 0 / 0.5)"); // { r: 255, g: 0, b: 0, a: 0.5 }
- * ```
- */
-export declare const parseRgb: (rgb: string) => RGB | RGBA | null;
-/**
- * Парсит HSL/HSLA строку в объект
- *
- * Поддерживаемые форматы:
- * - hsl(h, s%, l%)
- * - hsla(h, s%, l%, a)
- * - hsl(h s% l%)
- * - hsla(h s% l% / a)
- *
- * @param hsl - HSL/HSLA строка
- * @returns HSL или HSLA объект, или null если формат неверен
- *
- * @example
- * ```typescript
- * parseHsl("hsl(0, 100%, 50%)"); // { h: 0, s: 100, l: 50 }
- * parseHsl("hsla(0, 100%, 50%, 0.5)"); // { h: 0, s: 100, l: 50, a: 0.5 }
- * parseHsl("hsl(0 100% 50%)"); // { h: 0, s: 100, l: 50 }
- * ```
- */
-export declare const parseHsl: (hsl: string) => HSL | HSLA | null;
-/**
- * Универсальный парсер цвета
- *
- * Пробует распознать формат и парсит соответствующим парсером
- *
- * @param color - Строка цвета в любом поддерживаемом формате
- * @returns RGB или RGBA объект, или null если формат не распознан
- *
- * @example
- * ```typescript
- * parseColor("#ff0000"); // { r: 255, g: 0, b: 0 }
- * parseColor("rgb(255, 0, 0)"); // { r: 255, g: 0, b: 0 }
- * parseColor("hsl(0, 100%, 50%)"); // { r: 255, g: 0, b: 0 }
- * ```
- */
-export declare const parseColor: (color: string) => RGB | RGBA | null;
-/**
- * Конвертирует RGB/RGBA в HEX/HEXA строку
- *
- * @param rgb - RGB или RGBA объект
- * @returns HEX строка в формате #RRGGBB или #RRGGBBAA
- *
- * @example
- * ```typescript
- * rgbToHex({ r: 255, g: 0, b: 0 }); // "#ff0000"
- * rgbToHex({ r: 255, g: 0, b: 0, a: 0.5 }); // "#ff000080"
- * ```
- */
-export declare const rgbToHex: (rgb: RGB | RGBA) => HEX | HEXA;
-/**
- * Конвертирует HEX строку в RGB/RGBA объект
- *
- * @param hex - HEX строка
- * @returns RGB или RGBA объект
- * @throws {Error} Если формат HEX неверен
- *
- * @example
- * ```typescript
- * hexToRgb("#ff0000"); // { r: 255, g: 0, b: 0 }
- * hexToRgb("#f00"); // { r: 255, g: 0, b: 0 }
- * ```
- */
-export declare const hexToRgb: (hex: string) => RGB | RGBA;
-/**
- * Конвертирует RGB/RGBA в HSL/HSLA
- *
- * @param rgb - RGB или RGBA объект
- * @returns HSL или HSLA объект
- *
- * @example
- * ```typescript
- * rgbToHsl({ r: 255, g: 0, b: 0 }); // { h: 0, s: 100, l: 50 }
- * rgbToHsl({ r: 255, g: 255, b: 255 }); // { h: 0, s: 0, l: 100 }
- * ```
- */
-export declare const rgbToHsl: (rgb: RGB | RGBA) => HSL | HSLA;
-/**
- * Конвертирует HSL/HSLA в RGB/RGBA
- *
- * @param hsl - HSL или HSLA объект
- * @returns RGB или RGBA объект
- *
- * @example
- * ```typescript
- * hslToRgb({ h: 0, s: 100, l: 50 }); // { r: 255, g: 0, b: 0 }
- * hslToRgb({ h: 0, s: 0, l: 100 }); // { r: 255, g: 255, b: 255 }
- * ```
- */
-export declare const hslToRgb: (hsl: HSL | HSLA) => RGB | RGBA;
-/**
- * Конвертирует RGB/RGBA в HSV/HSVA
- *
- * @param rgb - RGB или RGBA объект
- * @returns HSV или HSVA объект
- *
- * @example
- * ```typescript
- * rgbToHsv({ r: 255, g: 0, b: 0 }); // { h: 0, s: 100, v: 100 }
- * rgbToHsv({ r: 0, g: 0, b: 0 }); // { h: 0, s: 0, v: 0 }
- * ```
- */
-export declare const rgbToHsv: (rgb: RGB | RGBA) => HSV | HSVA;
-/**
- * Конвертирует HSV/HSVA в RGB/RGBA
- *
- * @param hsv - HSV или HSVA объект
- * @returns RGB или RGBA объект
- *
- * @example
- * ```typescript
- * hsvToRgb({ h: 0, s: 100, v: 100 }); // { r: 255, g: 0, b: 0 }
- * hsvToRgb({ h: 0, s: 0, v: 0 }); // { r: 0, g: 0, b: 0 }
- * ```
- */
-export declare const hsvToRgb: (hsv: HSV | HSVA) => RGB | RGBA;
-/**
- * Форматирует RGB/RGBA в CSS-строку
- *
- * @param rgb - RGB или RGBA объект
- * @returns CSS-строка в формате rgb(r, g, b) или rgba(r, g, b, a)
- *
- * @example
- * ```typescript
- * toRgbString({ r: 255, g: 0, b: 0 }); // "rgb(255, 0, 0)"
- * toRgbString({ r: 255, g: 0, b: 0, a: 0.5 }); // "rgba(255, 0, 0, 0.5)"
- * ```
- */
-export declare const toRgbString: (rgb: RGB | RGBA) => string;
-/**
- * Форматирует RGB/RGBA в HEX-строку
- *
- * @param rgb - RGB или RGBA объект
- * @returns HEX-строка в формате #RRGGBB или #RRGGBBAA
- *
- * @example
- * ```typescript
- * toHexString({ r: 255, g: 0, b: 0 }); // "#ff0000"
- * toHexString({ r: 255, g: 0, b: 0, a: 0.5 }); // "#ff000080"
- * ```
- */
-export declare const toHexString: (rgb: RGB | RGBA) => string;
-/**
- * Форматирует HSL/HSLA в CSS-строку
- *
- * @param hsl - HSL или HSLA объект
- * @returns CSS-строка в формате hsl(h, s%, l%) или hsla(h, s%, l%, a)
- *
- * @example
- * ```typescript
- * toHslString({ h: 0, s: 100, l: 50 }); // "hsl(0, 100%, 50%)"
- * toHslString({ h: 0, s: 100, l: 50, a: 0.5 }); // "hsla(0, 100%, 50%, 0.5)"
- * ```
- */
-export declare const toHslString: (hsl: HSL | HSLA) => string;
-/**
- * Вычисляет относительную яркость цвета по формуле WCAG
- *
- * @param rgb - RGB объект
- * @returns Относительная яркость (0-1)
- *
- * @see https://www.w3.org/TR/WCAG20/#relativeluminancedef
- *
- * @example
- * ```typescript
- * getLuminance({ r: 255, g: 255, b: 255 }); // 1 (белый)
- * getLuminance({ r: 0, g: 0, b: 0 }); // 0 (чёрный)
- * getLuminance({ r: 255, g: 0, b: 0 }); // 0.2126 (красный)
- * ```
- */
-export declare const getLuminance: (rgb: RGB) => number;
-/**
- * Вычисляет контрастность между двумя цветами по формуле WCAG
- *
- * @param rgb1 - Первый RGB объект
- * @param rgb2 - Второй RGB объект
- * @returns Коэффициент контрастности (1-21)
- *
- * @see https://www.w3.org/TR/WCAG20/#contrast-ratiodef
- *
- * @example
- * ```typescript
- * getContrast({ r: 255, g: 255, b: 255 }, { r: 0, g: 0, b: 0 }); // 21 (максимальный контраст)
- * getContrast({ r: 255, g: 255, b: 255 }, { r: 255, g: 255, b: 255 }); // 1 (нет контраста)
- * ```
- */
-export declare const getContrast: (rgb1: RGB, rgb2: RGB) => number;
-/**
- * Класс для работы с цветами
- *
- * Поддерживает конвертацию между форматами, манипуляции с цветом и вычисление характеристик
- *
- * @example
- * ```typescript
- * const color = new Color("#ff0000");
- * color.rgb; // { r: 255, g: 0, b: 0 }
- * color.hex; // "#ff0000"
- * color.lighten(20).hex; // "#ff6666"
- * color.luminance(); // 0.2126
- * ```
- */
-export declare class Color {
-    private _rgb;
-    /**
-     * Создаёт экземпляр Color
-     *
-     * @param color - Строка цвета или RGB/RGBA объект
-     * @throws {Error} Если формат цвета не распознан
-     *
-     * @example
-     * ```typescript
-     * new Color("#ff0000");
-     * new Color("rgb(255, 0, 0)");
-     * new Color({ r: 255, g: 0, b: 0 });
-     * new Color({ r: 255, g: 0, b: 0, a: 0.5 });
-     * ```
-     */
-    constructor(color: string | RGB | RGBA);
-    /**
-     * Получает RGB представление цвета
-     */
-    get rgb(): RGB;
-    /**
-     * Получает RGBA представление цвета
-     */
-    get rgba(): RGBA;
-    /**
-     * Получает HSL представление цвета
-     */
-    get hsl(): HSL;
-    /**
-     * Получает HSLA представление цвета
-     */
-    get hsla(): HSLA;
-    /**
-     * Получает HSV представление цвета
-     */
-    get hsv(): HSV;
-    /**
-     * Получает HSVA представление цвета
-     */
-    get hsva(): HSVA;
-    /**
-     * Получает HEX представление цвета
-     */
-    get hex(): string;
-    /**
-     * Осветляет цвет
-     *
-     * @param amount - Процент осветления (0-100)
-     * @returns Новый экземпляр Color
-     *
-     * @example
-     * ```typescript
-     * new Color("#ff0000").lighten(20).hex; // "#ff6666"
-     * ```
-     */
-    lighten(amount: number): Color;
-    /**
-     * Затемняет цвет
-     *
-     * @param amount - Процент затемнения (0-100)
-     * @returns Новый экземпляр Color
-     *
-     * @example
-     * ```typescript
-     * new Color("#ff0000").darken(20).hex; // "#990000"
-     * ```
-     */
-    darken(amount: number): Color;
-    /**
-     * Увеличивает насыщенность цвета
-     *
-     * @param amount - Процент увеличения насыщенности (0-100)
-     * @returns Новый экземпляр Color
-     *
-     * @example
-     * ```typescript
-     * new Color("#ff6666").saturate(50).hex; // "#ff1a1a"
-     * ```
-     */
-    saturate(amount: number): Color;
-    /**
-     * Уменьшает насыщенность цвета
-     *
-     * @param amount - Процент уменьшения насыщенности (0-100)
-     * @returns Новый экземпляр Color
-     *
-     * @example
-     * ```typescript
-     * new Color("#ff0000").desaturate(50).hex; // "#bf4040"
-     * ```
-     */
-    desaturate(amount: number): Color;
-    /**
-     * Устанавливает прозрачность цвета
-     *
-     * @param alpha - Значение альфа-канала (0-1)
-     * @returns Новый экземпляр Color
-     *
-     * @example
-     * ```typescript
-     * new Color("#ff0000").opacity(0.5).hex; // "#ff000080"
-     * ```
-     */
-    opacity(alpha: number): Color;
-    /**
-     * Инвертирует цвет
-     *
-     * @returns Новый экземпляр Color
-     *
-     * @example
-     * ```typescript
-     * new Color("#ff0000").invert().hex; // "#00ffff"
-     * ```
-     */
-    invert(): Color;
-    /**
-     * Смешивает цвет с другим цветом
-     *
-     * @param color - Цвет для смешивания
-     * @param weight - Вес первого цвета (0-1), по умолчанию 0.5
-     * @returns Новый экземпляр Color
-     *
-     * @example
-     * ```typescript
-     * new Color("#ff0000").mix(new Color("#0000ff")).hex; // "#800080"
-     * new Color("#ff0000").mix(new Color("#0000ff"), 0.75).hex; // "#bf0040"
-     * ```
-     */
-    mix(color: Color, weight?: number): Color;
-    /**
-     * Вычисляет относительную яркость цвета
-     *
-     * @returns Относительная яркость (0-1)
-     *
-     * @example
-     * ```typescript
-     * new Color("#ffffff").luminance(); // 1
-     * new Color("#000000").luminance(); // 0
-     * ```
-     */
-    luminance(): number;
-    /**
-     * Вычисляет контрастность с другим цветом
-     *
-     * @param color - Цвет для сравнения
-     * @returns Коэффициент контрастности (1-21)
-     *
-     * @example
-     * ```typescript
-     * new Color("#ffffff").contrast(new Color("#000000")); // 21
-     * new Color("#ffffff").contrast(new Color("#ffffff")); // 1
-     * ```
-     */
-    contrast(color: Color): number;
-    /**
-     * Проверяет, является ли цвет светлым
-     *
-     * @returns true, если яркость > 0.5
-     *
-     * @example
-     * ```typescript
-     * new Color("#ffffff").isLight(); // true
-     * new Color("#000000").isLight(); // false
-     * ```
-     */
-    isLight(): boolean;
-    /**
-     * Проверяет, является ли цвет тёмным
-     *
-     * @returns true, если яркость <= 0.5
-     *
-     * @example
-     * ```typescript
-     * new Color("#000000").isDark(); // true
-     * new Color("#ffffff").isDark(); // false
-     * ```
-     */
-    isDark(): boolean;
-    /**
-     * Преобразует цвет в строку
-     *
-     * @param format - Формат вывода (hex, rgb, hsl), по умолчанию hex
-     * @returns Строковое представление цвета
-     *
-     * @example
-     * ```typescript
-     * new Color("#ff0000").toString(); // "#ff0000"
-     * new Color("#ff0000").toString("rgb"); // "rgb(255, 0, 0)"
-     * new Color("#ff0000").toString("hsl"); // "hsl(0, 100%, 50%)"
-     * ```
-     */
-    toString(format?: "hex" | "rgb" | "hsl"): string;
-}