@nemigo/helpers 0.13.1 → 0.13.3

package/dist/colors.js

@@ -0,0 +1,888 @@
+import { clamp, toRound, toZero } from "./phymath/index.js";
+//...
+/**
+ * Ограничивает значение RGB-канала в диапазоне 0-255
+ */
+export const clampRgb = (value) => clamp(Math.round(value), 0, 255);
+/**
+ * Ограничивает оттенок в диапазоне 0-360
+ */
+export const clampHue = (value) => {
+    const v = value % 360;
+    return toZero(v < 0 ? v + 360 : v);
+};
+/**
+ * Ограничивает процентное значение в диапазоне 0-100
+ */
+export const clampPercent = (value) => clamp(value, 0, 100);
+/**
+ * Ограничивает значение альфа-канала в диапазоне 0-1
+ */
+export const clampAlpha = (value) => clamp(value, 0, 1);
+//...
+/**
+ * Проверяет, является ли объект RGB
+ */
+const isRGB = (color) => typeof color === "object" && color !== null && "r" in color && "g" in color && "b" in color;
+/**
+ * Проверяет, является ли объект RGBA
+ */
+const isRGBA = (color) => isRGB(color) && "a" in color;
+/**
+ * Проверяет, является ли объект HSL
+ */
+const isHSL = (color) => typeof color === "object" && color !== null && "h" in color && "s" in color && "l" in color;
+/**
+ * Проверяет, является ли объект HSLA
+ */
+const isHSLA = (color) => isHSL(color) && "a" in color;
+/**
+ * Проверяет, является ли объект HSV
+ */
+const isHSV = (color) => typeof color === "object" && color !== null && "h" in color && "s" in color && "v" in color;
+/**
+ * Проверяет, является ли объект HSVA
+ */
+const isHSVA = (color) => isHSV(color) && "a" in color;
+//...
+/**
+ * Парсит 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 const parseHex = (hex) => {
+    const cleaned = hex.trim().replace(/^#/, "");
+    // #RGB или #RGBA
+    if (cleaned.length === 3 || cleaned.length === 4) {
+        const r = parseInt(cleaned[0] + cleaned[0], 16);
+        const g = parseInt(cleaned[1] + cleaned[1], 16);
+        const b = parseInt(cleaned[2] + cleaned[2], 16);
+        if (isNaN(r) || isNaN(g) || isNaN(b))
+            return null;
+        if (cleaned.length === 4) {
+            const a = parseInt(cleaned[3] + cleaned[3], 16) / 255;
+            if (isNaN(a))
+                return null;
+            return { r, g, b, a: toRound(a, 3) };
+        }
+        return { r, g, b };
+    }
+    // #RRGGBB или #RRGGBBAA
+    if (cleaned.length === 6 || cleaned.length === 8) {
+        const r = parseInt(cleaned.substring(0, 2), 16);
+        const g = parseInt(cleaned.substring(2, 4), 16);
+        const b = parseInt(cleaned.substring(4, 6), 16);
+        if (isNaN(r) || isNaN(g) || isNaN(b))
+            return null;
+        if (cleaned.length === 8) {
+            const a = parseInt(cleaned.substring(6, 8), 16) / 255;
+            if (isNaN(a))
+                return null;
+            return { r, g, b, a: toRound(a, 3) };
+        }
+        return { r, g, b };
+    }
+    return 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 const parseRgb = (rgb) => {
+    const match = rgb.trim().match(/^rgba?\(\s*([^)]+)\s*\)$/i);
+    if (!match)
+        return null;
+    const parts = match[1]
+        .split(/[\s,/]+/)
+        .map((v) => v.trim())
+        .filter((v) => v !== "");
+    if (parts.length < 3 || parts.length > 4)
+        return null;
+    const r = parseInt(parts[0], 10);
+    const g = parseInt(parts[1], 10);
+    const b = parseInt(parts[2], 10);
+    if (isNaN(r) || isNaN(g) || isNaN(b))
+        return null;
+    if (parts.length === 4) {
+        const a = parseFloat(parts[3]);
+        if (isNaN(a))
+            return null;
+        return { r: clampRgb(r), g: clampRgb(g), b: clampRgb(b), a: clampAlpha(a) };
+    }
+    return { r: clampRgb(r), g: clampRgb(g), b: clampRgb(b) };
+};
+/**
+ * Парсит 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 const parseHsl = (hsl) => {
+    const match = hsl.trim().match(/^hsla?\(\s*([^)]+)\s*\)$/i);
+    if (!match)
+        return null;
+    const parts = match[1]
+        .split(/[\s,/]+/)
+        .map((v) => v.trim())
+        .filter((v) => v !== "");
+    if (parts.length < 3 || parts.length > 4)
+        return null;
+    const h = parseFloat(parts[0]);
+    const s = parseFloat(parts[1].replace("%", ""));
+    const l = parseFloat(parts[2].replace("%", ""));
+    if (isNaN(h) || isNaN(s) || isNaN(l))
+        return null;
+    if (parts.length === 4) {
+        const a = parseFloat(parts[3]);
+        if (isNaN(a))
+            return null;
+        return { h: clampHue(h), s: clampPercent(s), l: clampPercent(l), a: clampAlpha(a) };
+    }
+    return { h: clampHue(h), s: clampPercent(s), l: clampPercent(l) };
+};
+/**
+ * Универсальный парсер цвета
+ *
+ * Пробует распознать формат и парсит соответствующим парсером
+ *
+ * @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 const parseColor = (color) => {
+    const trimmed = color.trim();
+    // Пробуем HEX
+    if (trimmed.startsWith("#")) {
+        return parseHex(trimmed);
+    }
+    // Пробуем RGB/RGBA
+    if (trimmed.startsWith("rgb")) {
+        return parseRgb(trimmed);
+    }
+    // Пробуем HSL/HSLA (конвертируем в RGB)
+    if (trimmed.startsWith("hsl")) {
+        const hsl = parseHsl(trimmed);
+        if (hsl)
+            return hslToRgb(hsl);
+    }
+    return 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 const rgbToHex = (rgb) => {
+    const r = clampRgb(rgb.r).toString(16).padStart(2, "0");
+    const g = clampRgb(rgb.g).toString(16).padStart(2, "0");
+    const b = clampRgb(rgb.b).toString(16).padStart(2, "0");
+    if (isRGBA(rgb)) {
+        const a = Math.round(clampAlpha(rgb.a) * 255)
+            .toString(16)
+            .padStart(2, "0");
+        return `#${r}${g}${b}${a}`;
+    }
+    return `#${r}${g}${b}`;
+};
+/**
+ * Конвертирует 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 const hexToRgb = (hex) => {
+    const result = parseHex(hex);
+    if (!result)
+        throw new Error(`Неверный HEX формат: ${hex}`);
+    return result;
+};
+/**
+ * Конвертирует 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 const rgbToHsl = (rgb) => {
+    const r = rgb.r / 255;
+    const g = rgb.g / 255;
+    const b = rgb.b / 255;
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    const delta = max - min;
+    let h = 0;
+    let s = 0;
+    const l = (max + min) / 2;
+    if (delta !== 0) {
+        s = l > 0.5 ? delta / (2 - max - min) : delta / (max + min);
+        switch (max) {
+            case r:
+                h = ((g - b) / delta + (g < b ? 6 : 0)) / 6;
+                break;
+            case g:
+                h = ((b - r) / delta + 2) / 6;
+                break;
+            case b:
+                h = ((r - g) / delta + 4) / 6;
+                break;
+        }
+    }
+    const result = {
+        h: toRound(h * 360, 1),
+        s: toRound(s * 100, 1),
+        l: toRound(l * 100, 1),
+    };
+    if (isRGBA(rgb)) {
+        return { ...result, a: rgb.a };
+    }
+    return result;
+};
+/**
+ * Конвертирует 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 const hslToRgb = (hsl) => {
+    const h = hsl.h / 360;
+    const s = hsl.s / 100;
+    const l = hsl.l / 100;
+    let r, g, b;
+    if (s === 0) {
+        r = g = b = l;
+    }
+    else {
+        const hue2rgb = (p, q, t) => {
+            if (t < 0)
+                t += 1;
+            if (t > 1)
+                t -= 1;
+            if (t < 1 / 6)
+                return p + (q - p) * 6 * t;
+            if (t < 1 / 2)
+                return q;
+            if (t < 2 / 3)
+                return p + (q - p) * (2 / 3 - t) * 6;
+            return p;
+        };
+        const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+        const p = 2 * l - q;
+        r = hue2rgb(p, q, h + 1 / 3);
+        g = hue2rgb(p, q, h);
+        b = hue2rgb(p, q, h - 1 / 3);
+    }
+    const result = {
+        r: Math.round(r * 255),
+        g: Math.round(g * 255),
+        b: Math.round(b * 255),
+    };
+    if (isHSLA(hsl)) {
+        return { ...result, a: hsl.a };
+    }
+    return result;
+};
+/**
+ * Конвертирует 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 const rgbToHsv = (rgb) => {
+    const r = rgb.r / 255;
+    const g = rgb.g / 255;
+    const b = rgb.b / 255;
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    const delta = max - min;
+    let h = 0;
+    let s = 0;
+    const v = max;
+    if (delta !== 0) {
+        s = delta / max;
+        switch (max) {
+            case r:
+                h = ((g - b) / delta + (g < b ? 6 : 0)) / 6;
+                break;
+            case g:
+                h = ((b - r) / delta + 2) / 6;
+                break;
+            case b:
+                h = ((r - g) / delta + 4) / 6;
+                break;
+        }
+    }
+    const result = {
+        h: toRound(h * 360, 1),
+        s: toRound(s * 100, 1),
+        v: toRound(v * 100, 1),
+    };
+    if (isRGBA(rgb)) {
+        return { ...result, a: rgb.a };
+    }
+    return result;
+};
+/**
+ * Конвертирует 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 const hsvToRgb = (hsv) => {
+    const h = hsv.h / 360;
+    const s = hsv.s / 100;
+    const v = hsv.v / 100;
+    const i = Math.floor(h * 6);
+    const f = h * 6 - i;
+    const p = v * (1 - s);
+    const q = v * (1 - f * s);
+    const t = v * (1 - (1 - f) * s);
+    let r, g, b;
+    switch (i % 6) {
+        case 0:
+            r = v;
+            g = t;
+            b = p;
+            break;
+        case 1:
+            r = q;
+            g = v;
+            b = p;
+            break;
+        case 2:
+            r = p;
+            g = v;
+            b = t;
+            break;
+        case 3:
+            r = p;
+            g = q;
+            b = v;
+            break;
+        case 4:
+            r = t;
+            g = p;
+            b = v;
+            break;
+        case 5:
+        default:
+            r = v;
+            g = p;
+            b = q;
+            break;
+    }
+    const result = {
+        r: Math.round(r * 255),
+        g: Math.round(g * 255),
+        b: Math.round(b * 255),
+    };
+    if (isHSVA(hsv)) {
+        return { ...result, a: hsv.a };
+    }
+    return result;
+};
+//...
+/**
+ * Форматирует 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 const toRgbString = (rgb) => {
+    if (isRGBA(rgb)) {
+        return `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${toRound(rgb.a, 3)})`;
+    }
+    return `rgb(${rgb.r}, ${rgb.g}, ${rgb.b})`;
+};
+/**
+ * Форматирует 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 const toHexString = (rgb) => rgbToHex(rgb);
+/**
+ * Форматирует 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 const toHslString = (hsl) => {
+    if (isHSLA(hsl)) {
+        return `hsla(${toRound(hsl.h, 1)}, ${toRound(hsl.s, 1)}%, ${toRound(hsl.l, 1)}%, ${toRound(hsl.a, 3)})`;
+    }
+    return `hsl(${toRound(hsl.h, 1)}, ${toRound(hsl.s, 1)}%, ${toRound(hsl.l, 1)}%)`;
+};
+//...
+/**
+ * Вычисляет относительную яркость цвета по формуле 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 const getLuminance = (rgb) => {
+    const rsRGB = rgb.r / 255;
+    const gsRGB = rgb.g / 255;
+    const bsRGB = rgb.b / 255;
+    const r = rsRGB <= 0.03928 ? rsRGB / 12.92 : Math.pow((rsRGB + 0.055) / 1.055, 2.4);
+    const g = gsRGB <= 0.03928 ? gsRGB / 12.92 : Math.pow((gsRGB + 0.055) / 1.055, 2.4);
+    const b = bsRGB <= 0.03928 ? bsRGB / 12.92 : Math.pow((bsRGB + 0.055) / 1.055, 2.4);
+    return toRound(0.2126 * r + 0.7152 * g + 0.0722 * b, 4);
+};
+/**
+ * Вычисляет контрастность между двумя цветами по формуле 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 const getContrast = (rgb1, rgb2) => {
+    const lum1 = getLuminance(rgb1);
+    const lum2 = getLuminance(rgb2);
+    const lighter = Math.max(lum1, lum2);
+    const darker = Math.min(lum1, lum2);
+    return toRound((lighter + 0.05) / (darker + 0.05), 2);
+};
+//...
+/**
+ * Класс для работы с цветами
+ *
+ * Поддерживает конвертацию между форматами, манипуляции с цветом и вычисление характеристик
+ *
+ * @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 class Color {
+    _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) {
+        if (typeof color === "string") {
+            const parsed = parseColor(color);
+            if (!parsed)
+                throw new Error(`Не удалось распознать цвет: ${color}`);
+            this._rgb = isRGBA(parsed) ? parsed : { ...parsed, a: 1 };
+        }
+        else if (isRGBA(color)) {
+            this._rgb = {
+                r: clampRgb(color.r),
+                g: clampRgb(color.g),
+                b: clampRgb(color.b),
+                a: clampAlpha(color.a),
+            };
+        }
+        else {
+            this._rgb = {
+                r: clampRgb(color.r),
+                g: clampRgb(color.g),
+                b: clampRgb(color.b),
+                a: 1,
+            };
+        }
+    }
+    /**
+     * Получает RGB представление цвета
+     */
+    get rgb() {
+        return { r: this._rgb.r, g: this._rgb.g, b: this._rgb.b };
+    }
+    /**
+     * Получает RGBA представление цвета
+     */
+    get rgba() {
+        return { ...this._rgb };
+    }
+    /**
+     * Получает HSL представление цвета
+     */
+    get hsl() {
+        const result = rgbToHsl(this._rgb);
+        if (isHSLA(result)) {
+            const { a, ...hsl } = result;
+            return hsl;
+        }
+        return result;
+    }
+    /**
+     * Получает HSLA представление цвета
+     */
+    get hsla() {
+        const result = rgbToHsl(this._rgb);
+        if (isHSLA(result))
+            return result;
+        return { ...result, a: this._rgb.a };
+    }
+    /**
+     * Получает HSV представление цвета
+     */
+    get hsv() {
+        const result = rgbToHsv(this._rgb);
+        if (isHSVA(result)) {
+            const { a, ...hsv } = result;
+            return hsv;
+        }
+        return result;
+    }
+    /**
+     * Получает HSVA представление цвета
+     */
+    get hsva() {
+        const result = rgbToHsv(this._rgb);
+        if (isHSVA(result))
+            return result;
+        return { ...result, a: this._rgb.a };
+    }
+    /**
+     * Получает HEX представление цвета
+     */
+    get hex() {
+        if (this._rgb.a < 1) {
+            return rgbToHex(this._rgb);
+        }
+        return rgbToHex(this.rgb);
+    }
+    /**
+     * Осветляет цвет
+     *
+     * @param amount - Процент осветления (0-100)
+     * @returns Новый экземпляр Color
+     *
+     * @example
+     * ```typescript
+     * new Color("#ff0000").lighten(20).hex; // "#ff6666"
+     * ```
+     */
+    lighten(amount) {
+        const hsl = this.hsla;
+        hsl.l = clampPercent(hsl.l + amount);
+        return new Color(hslToRgb(hsl));
+    }
+    /**
+     * Затемняет цвет
+     *
+     * @param amount - Процент затемнения (0-100)
+     * @returns Новый экземпляр Color
+     *
+     * @example
+     * ```typescript
+     * new Color("#ff0000").darken(20).hex; // "#990000"
+     * ```
+     */
+    darken(amount) {
+        const hsl = this.hsla;
+        hsl.l = clampPercent(hsl.l - amount);
+        return new Color(hslToRgb(hsl));
+    }
+    /**
+     * Увеличивает насыщенность цвета
+     *
+     * @param amount - Процент увеличения насыщенности (0-100)
+     * @returns Новый экземпляр Color
+     *
+     * @example
+     * ```typescript
+     * new Color("#ff6666").saturate(50).hex; // "#ff1a1a"
+     * ```
+     */
+    saturate(amount) {
+        const hsl = this.hsla;
+        hsl.s = clampPercent(hsl.s + amount);
+        return new Color(hslToRgb(hsl));
+    }
+    /**
+     * Уменьшает насыщенность цвета
+     *
+     * @param amount - Процент уменьшения насыщенности (0-100)
+     * @returns Новый экземпляр Color
+     *
+     * @example
+     * ```typescript
+     * new Color("#ff0000").desaturate(50).hex; // "#bf4040"
+     * ```
+     */
+    desaturate(amount) {
+        const hsl = this.hsla;
+        hsl.s = clampPercent(hsl.s - amount);
+        return new Color(hslToRgb(hsl));
+    }
+    /**
+     * Устанавливает прозрачность цвета
+     *
+     * @param alpha - Значение альфа-канала (0-1)
+     * @returns Новый экземпляр Color
+     *
+     * @example
+     * ```typescript
+     * new Color("#ff0000").opacity(0.5).hex; // "#ff000080"
+     * ```
+     */
+    opacity(alpha) {
+        return new Color({ ...this._rgb, a: clampAlpha(alpha) });
+    }
+    /**
+     * Инвертирует цвет
+     *
+     * @returns Новый экземпляр Color
+     *
+     * @example
+     * ```typescript
+     * new Color("#ff0000").invert().hex; // "#00ffff"
+     * ```
+     */
+    invert() {
+        return new Color({
+            r: 255 - this._rgb.r,
+            g: 255 - this._rgb.g,
+            b: 255 - this._rgb.b,
+            a: this._rgb.a,
+        });
+    }
+    /**
+     * Смешивает цвет с другим цветом
+     *
+     * @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, weight = 0.5) {
+        const w = clampAlpha(weight);
+        const w1 = w;
+        const w2 = 1 - w;
+        const rgba1 = this._rgb;
+        const rgba2 = color._rgb;
+        return new Color({
+            r: Math.round(rgba1.r * w1 + rgba2.r * w2),
+            g: Math.round(rgba1.g * w1 + rgba2.g * w2),
+            b: Math.round(rgba1.b * w1 + rgba2.b * w2),
+            a: rgba1.a * w1 + rgba2.a * w2,
+        });
+    }
+    /**
+     * Вычисляет относительную яркость цвета
+     *
+     * @returns Относительная яркость (0-1)
+     *
+     * @example
+     * ```typescript
+     * new Color("#ffffff").luminance(); // 1
+     * new Color("#000000").luminance(); // 0
+     * ```
+     */
+    luminance() {
+        return getLuminance(this.rgb);
+    }
+    /**
+     * Вычисляет контрастность с другим цветом
+     *
+     * @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) {
+        return getContrast(this.rgb, color.rgb);
+    }
+    /**
+     * Проверяет, является ли цвет светлым
+     *
+     * @returns true, если яркость > 0.5
+     *
+     * @example
+     * ```typescript
+     * new Color("#ffffff").isLight(); // true
+     * new Color("#000000").isLight(); // false
+     * ```
+     */
+    isLight() {
+        return this.luminance() > 0.5;
+    }
+    /**
+     * Проверяет, является ли цвет тёмным
+     *
+     * @returns true, если яркость <= 0.5
+     *
+     * @example
+     * ```typescript
+     * new Color("#000000").isDark(); // true
+     * new Color("#ffffff").isDark(); // false
+     * ```
+     */
+    isDark() {
+        return !this.isLight();
+    }
+    /**
+     * Преобразует цвет в строку
+     *
+     * @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") {
+        switch (format) {
+            case "rgb":
+                return toRgbString(this._rgb);
+            case "hsl":
+                return toHslString(this.hsla);
+            case "hex":
+            default:
+                return this.hex;
+        }
+    }
+}