omni-color 0.1.0

package/dist/src/color/utils.js

@@ -0,0 +1,142 @@
+import { clampValue, resolveCaseInsensitiveOption } from '../utils';
+import { Color } from './color';
+import { CSS_COLOR_NAME_TO_HEX_MAP } from './color.consts';
+import { toRGBA } from './conversions';
+import { parseCSSColorFormatString } from './parse';
+import { getRandomColorRGBA } from './random';
+import { getColorFromTemperatureLabel, matchPartialColorTemperatureLabel } from './temperature';
+export function getColorRGBAFromInput(color) {
+    if (color instanceof Color) {
+        return color.toRGBA();
+    }
+    if (typeof color === 'string') {
+        const colorString = color.trim().toLowerCase();
+        // Hex string (e.g. "#ff0000"):
+        if (colorString.startsWith('#')) {
+            return toRGBA(colorString);
+        }
+        // Named color (e.g. "red"):
+        const namedColorHex = CSS_COLOR_NAME_TO_HEX_MAP[colorString.replace(/ /g, '')];
+        if (namedColorHex) {
+            return toRGBA(namedColorHex);
+        }
+        const matchedColorTemperatureLabel = matchPartialColorTemperatureLabel(colorString);
+        if (matchedColorTemperatureLabel) {
+            return getColorFromTemperatureLabel(matchedColorTemperatureLabel).toRGBA();
+        }
+        // Other CSS color format string (e.g. "rgb(255, 0, 0)"):
+        const parsedColor = parseCSSColorFormatString(colorString);
+        if (parsedColor) {
+            return parsedColor.toRGBA();
+        }
+        throw new Error(`unknown color name or format: "${color}"`);
+    }
+    return color ? toRGBA(color) : getRandomColorRGBA();
+}
+const RGB_CHANNEL_MAX_VALUE = 255; // 8‑bit channel ceiling
+const SRGB_LINEAR_SEGMENT_DIVISOR = 12.92; // slope for low‑intensity segment
+const SRGB_GAMMA_OFFSET = 0.055; // additive term in sRGB gamma curve
+const SRGB_GAMMA_SCALE = 1.055; // multiplicative term in sRGB gamma curve
+const SRGB_GAMMA_EXPONENT = 2.4; // exponent in sRGB transfer function
+const SRGB_GAMMA_PIVOT_OPTIONS = {
+    SRGB: 0.04045,
+    WCAG: 0.03928,
+};
+// Does a gamma correction by converting the given sRGB channel value (0 to 255)
+// to a linear RGB channel value (0 to 1).
+export function srgbChannelToLinear(srgbChannelVal, pivot) {
+    const c = clampValue(srgbChannelVal, 0, RGB_CHANNEL_MAX_VALUE) / RGB_CHANNEL_MAX_VALUE; // normalize
+    let result;
+    if (c <= SRGB_GAMMA_PIVOT_OPTIONS[pivot]) {
+        result = c / SRGB_LINEAR_SEGMENT_DIVISOR; // linear portion for dark colors
+    }
+    else {
+        result = Math.pow((c + SRGB_GAMMA_OFFSET) / SRGB_GAMMA_SCALE, SRGB_GAMMA_EXPONENT); // gamma correction for brighter colors
+    }
+    return clampValue(result, 0, 1);
+}
+// Inverts `srgbChannelToLinear()`. Takes a linearized channel value (0 to 1) and returns
+// the original sRGB channel value (0 to 255).
+export function linearChannelToSrgb(linearChannelVal, pivot) {
+    const c = clampValue(linearChannelVal, 0, 1);
+    const threshold = SRGB_GAMMA_PIVOT_OPTIONS[pivot] / SRGB_LINEAR_SEGMENT_DIVISOR;
+    let result;
+    if (c > threshold) {
+        result = SRGB_GAMMA_SCALE * Math.pow(c, 1 / SRGB_GAMMA_EXPONENT) - SRGB_GAMMA_OFFSET;
+    }
+    else {
+        result = c * SRGB_LINEAR_SEGMENT_DIVISOR;
+    }
+    return clampValue(result * RGB_CHANNEL_MAX_VALUE, 0, RGB_CHANNEL_MAX_VALUE);
+}
+export function getRelativeLuminance(rgb) {
+    const r = srgbChannelToLinear(rgb.r, 'WCAG');
+    const g = srgbChannelToLinear(rgb.g, 'WCAG');
+    const b = srgbChannelToLinear(rgb.b, 'WCAG');
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b; // standard luminance formula
+}
+/**
+ * The algorithm mode to use for calculating if a color is dark.
+ */
+const COLOR_DARKNESS_MODES = ['WCAG', 'YIQ'];
+function isColorDarkWCAG(color, threshold) {
+    return getRelativeLuminance(color.toRGBA()) < threshold;
+}
+function isColorDarkYIQ(color, threshold) {
+    // Weighted RGB luminance calculation:
+    const { r, g, b } = color.toRGB();
+    const brightness = (299 * r + 587 * g + 114 * b) / 1000;
+    return brightness < threshold;
+}
+// Checks if a color is dark based on the specified algorithm and threshold.
+export function isColorDark(color, options = {}) {
+    const colorDarknessMode = resolveCaseInsensitiveOption({
+        allowedValues: COLOR_DARKNESS_MODES,
+        defaultValue: 'WCAG',
+        key: 'colorDarknessMode',
+        options,
+    });
+    if (colorDarknessMode === 'YIQ') {
+        return isColorDarkYIQ(color, options.yiqThreshold ?? 128);
+    }
+    return isColorDarkWCAG(color, options.wcagThreshold ?? 0.179);
+}
+export function isColorOffWhite(color) {
+    const { r, g, b } = color.toRGB();
+    const brightness = (299 * r + 587 * g + 114 * b) / 1000;
+    const maxChannel = Math.max(r, g, b);
+    const minChannel = Math.min(r, g, b);
+    return brightness >= 240 && maxChannel - minChannel <= 30;
+}
+const RGB_CHANNEL_EPSILON = 1e-2; // allow minor floating‑point drift on RGB channels
+const ALPHA_EPSILON = 1e-6; // alpha values should match unless the difference is imperceptible floating‑point noise
+function normalizeChannel(value) {
+    const rounded = Math.round(value);
+    return Math.abs(value - rounded) <= RGB_CHANNEL_EPSILON ? rounded : value;
+}
+function normalizeAlpha(value) {
+    const rounded = Math.round(value * 1000) / 1000;
+    return Math.abs(value - rounded) <= ALPHA_EPSILON ? rounded : value;
+}
+export function areColorsEqual(color1, color2) {
+    const c1 = color1.toRGBA();
+    const c2 = color2.toRGBA();
+    const r1 = normalizeChannel(c1.r);
+    const g1 = normalizeChannel(c1.g);
+    const b1 = normalizeChannel(c1.b);
+    const r2 = normalizeChannel(c2.r);
+    const g2 = normalizeChannel(c2.g);
+    const b2 = normalizeChannel(c2.b);
+    const a1 = normalizeAlpha(c1.a ?? 1);
+    const a2 = normalizeAlpha(c2.a ?? 1);
+    return r1 === r2 && g1 === g2 && b1 === b2 && Math.abs(a1 - a2) <= ALPHA_EPSILON;
+}
+function isColor(value) {
+    return value instanceof Color;
+}
+export function getColorList(candidates) {
+    if (Array.isArray(candidates)) {
+        return candidates.map((candidate) => (isColor(candidate) ? candidate : new Color(candidate)));
+    }
+    return Object.values(candidates).filter(isColor);
+}

package/dist/src/color/validations.d.ts

@@ -0,0 +1,2 @@
+import type { ColorFormat } from './formats';
+export declare function validateColorOrThrow(color?: ColorFormat | null): void;

package/dist/src/color/validations.js

@@ -0,0 +1,178 @@
+import { getColorFormatType } from './formats';
+const HEX_COLOR_REGEX = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+function isValidHexColor(color) {
+    return HEX_COLOR_REGEX.test(color);
+}
+function isValueInRangeInclusive(value, min, max) {
+    return typeof value === 'number' && value >= min && value <= max;
+}
+function isValidAlphaValue(value) {
+    return value === undefined || (typeof value === 'number' && value >= 0 && value <= 1);
+}
+function isValidRGBColor(color) {
+    const { r, g, b } = color;
+    return (isValueInRangeInclusive(r, 0, 255) &&
+        isValueInRangeInclusive(g, 0, 255) &&
+        isValueInRangeInclusive(b, 0, 255));
+}
+function isValidRGBAColor(color) {
+    return isValidRGBColor(color) && isValidAlphaValue(color.a);
+}
+function isValidHSLColor(color) {
+    const { h, s, l } = color;
+    return (isValueInRangeInclusive(h, 0, 360) &&
+        isValueInRangeInclusive(s, 0, 100) &&
+        isValueInRangeInclusive(l, 0, 100));
+}
+function isValidHSLAColor(color) {
+    return isValidHSLColor(color) && isValidAlphaValue(color.a);
+}
+function isValidHSVColor(color) {
+    const { h, s, v } = color;
+    return (isValueInRangeInclusive(h, 0, 360) &&
+        isValueInRangeInclusive(s, 0, 100) &&
+        isValueInRangeInclusive(v, 0, 100));
+}
+function isValidHSVAColor(color) {
+    return isValidHSVColor(color) && isValidAlphaValue(color.a);
+}
+function isValidHWBColor(color) {
+    const { h, w, b } = color;
+    return (isValueInRangeInclusive(h, 0, 360) &&
+        isValueInRangeInclusive(w, 0, 100) &&
+        isValueInRangeInclusive(b, 0, 100));
+}
+function isValidHWBAColor(color) {
+    return isValidHWBColor(color) && isValidAlphaValue(color.a);
+}
+function isValidCMYKColor(color) {
+    const { c, m, y, k } = color;
+    const check = (value) => typeof value === 'number' && value >= 0 && value <= 100;
+    return [c, m, y, k].every(check);
+}
+function isValidLABColor(color) {
+    const { l, a, b } = color;
+    return (typeof l === 'number' &&
+        l >= 0 &&
+        l <= 100 &&
+        typeof a === 'number' &&
+        Number.isFinite(a) &&
+        typeof b === 'number' &&
+        Number.isFinite(b));
+}
+function isValidOKLABColor(color) {
+    const { l, a, b } = color;
+    return (typeof l === 'number' &&
+        l >= 0 &&
+        l <= 1 &&
+        typeof a === 'number' &&
+        Number.isFinite(a) &&
+        typeof b === 'number' &&
+        Number.isFinite(b));
+}
+function isValidLCHColor(color) {
+    const { l, c, h } = color;
+    return (typeof l === 'number' &&
+        l >= 0 &&
+        l <= 100 &&
+        typeof c === 'number' &&
+        c >= 0 &&
+        typeof h === 'number' &&
+        h >= 0 &&
+        h <= 360);
+}
+function isValidOKLCHColor(color) {
+    const { l, c, h } = color;
+    return (typeof l === 'number' &&
+        l >= 0 &&
+        l <= 1 &&
+        typeof c === 'number' &&
+        c >= 0 &&
+        typeof h === 'number' &&
+        h >= 0 &&
+        h <= 360);
+}
+export function validateColorOrThrow(color) {
+    if (color === undefined) {
+        throw new Error('color is undefined');
+    }
+    if (color === null) {
+        throw new Error('color is null');
+    }
+    const { formatType, value } = getColorFormatType(color);
+    switch (formatType) {
+        case 'HEX':
+        case 'HEX8':
+            if (!isValidHexColor(value)) {
+                throw new Error(`invalid hex color: "${value}"`);
+            }
+            break;
+        case 'RGB':
+            if (!isValidRGBColor(value)) {
+                throw new Error(`invalid RGB color: "${JSON.stringify(value)}"`);
+            }
+            break;
+        case 'RGBA':
+            if (!isValidRGBAColor(value)) {
+                throw new Error(`invalid RGBA color: "${JSON.stringify(value)}"`);
+            }
+            break;
+        case 'HSL':
+            if (!isValidHSLColor(value)) {
+                throw new Error(`invalid HSL color: "${JSON.stringify(value)}"`);
+            }
+            break;
+        case 'HSLA':
+            if (!isValidHSLAColor(value)) {
+                throw new Error(`invalid HSLA color: "${JSON.stringify(value)}"`);
+            }
+            break;
+        case 'HSV':
+            if (!isValidHSVColor(value)) {
+                throw new Error(`invalid HSV color: "${JSON.stringify(value)}"`);
+            }
+            break;
+        case 'HSVA':
+            if (!isValidHSVAColor(value)) {
+                throw new Error(`invalid HSVA color: "${JSON.stringify(value)}"`);
+            }
+            break;
+        case 'HWB':
+            if (!isValidHWBColor(value)) {
+                throw new Error(`invalid HWB color: "${JSON.stringify(value)}"`);
+            }
+            break;
+        case 'HWBA':
+            if (!isValidHWBAColor(value)) {
+                throw new Error(`invalid HWBA color: "${JSON.stringify(value)}"`);
+            }
+            break;
+        case 'CMYK':
+            if (!isValidCMYKColor(value)) {
+                throw new Error(`invalid CMYK color: "${JSON.stringify(value)}"`);
+            }
+            break;
+        case 'LAB':
+            if (!isValidLABColor(value)) {
+                throw new Error(`invalid LAB color: "${JSON.stringify(value)}"`);
+            }
+            break;
+        case 'OKLAB':
+            if (!isValidOKLABColor(value)) {
+                throw new Error(`invalid OKLAB color: "${JSON.stringify(value)}"`);
+            }
+            break;
+        case 'LCH':
+            if (!isValidLCHColor(value)) {
+                throw new Error(`invalid LCH color: "${JSON.stringify(value)}"`);
+            }
+            break;
+        case 'OKLCH':
+            if (!isValidOKLCHColor(value)) {
+                throw new Error(`invalid OKLCH color: "${JSON.stringify(value)}"`);
+            }
+            break;
+        default:
+            throw new Error(`unknown color format: "${formatType}"`);
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,20 @@
+import { Color } from './color/color';
+import type { ColorSpace, ColorStringOptions } from './color/colorSpaces';
+import type { BlendMode, BlendSpace, MixSpace, MixType } from './color/combinations';
+import { AverageColorsOptions, BlendColorsOptions, MixColorsOptions } from './color/combinations';
+import type { CIE94Options, CIEDE2000Options, DeltaEMethod, DeltaEOptions } from './color/deltaE';
+import { ColorCMYK, type ColorFormat, ColorHex, ColorHSL, ColorHSLA, ColorHSV, ColorHSVA, ColorHWB, ColorHWBA, ColorLAB, ColorLCH, ColorOKLAB, ColorOKLCH, ColorRGB, ColorRGBA } from './color/formats';
+import type { ColorGradientEasing, ColorGradientInterpolation, ColorGradientOptions, ColorGradientSpace, HueInterpolationMode } from './color/gradients';
+import type { ColorHarmony, ColorHarmonyOptions, GrayscaleHandlingMode } from './color/harmonies';
+import type { ColorBrightnessOptions, ColorBrightnessSpace, ColorSaturationOptions, ColorSaturationSpace } from './color/manipulations';
+import type { BaseColorName, ColorLightnessModifier } from './color/names';
+import { ColorNameAndLightness } from './color/names';
+import { RandomColorOptions } from './color/random';
+import type { APCAReadabilityOptions, APCAReadabilityPolicy, APCAReadabilityReport, APCAThresholdPreset, ReadabilityAlgorithm, ReadabilityOptions, WCAGReadabilityConformanceLevel, WCAGReadabilityTextSizeOptions } from './color/readability';
+import { WCAGReadabilityOptions, WCAGReadabilityReport } from './color/readability';
+import { ColorSwatch, ColorSwatchOptions, ExtendedColorSwatch } from './color/swatch';
+import type { ColorTemperatureLabel } from './color/temperature';
+import { ColorTemperatureAndLabel, ColorTemperatureStringFormatOptions } from './color/temperature';
+import { ColorDarknessMode, IsColorDarkOptions } from './color/utils';
+import { ColorPalette, GenerateColorPaletteOptions } from './palette/palette';
+export { APCAReadabilityOptions, type APCAReadabilityPolicy, APCAReadabilityReport, type APCAThresholdPreset, AverageColorsOptions, type BaseColorName, BlendColorsOptions, type BlendMode, type BlendSpace, type CIE94Options, type CIEDE2000Options, Color, ColorBrightnessOptions, type ColorBrightnessSpace, ColorCMYK, ColorDarknessMode, type ColorFormat, ColorGradientEasing, ColorGradientInterpolation, ColorGradientOptions, ColorGradientSpace, type ColorHarmony, type ColorHarmonyOptions, ColorHex, ColorHSL, ColorHSLA, ColorHSV, ColorHSVA, ColorHWB, ColorHWBA, ColorLAB, ColorLCH, type ColorLightnessModifier, ColorNameAndLightness, ColorOKLAB, ColorOKLCH, ColorPalette, ColorRGB, ColorRGBA, ColorSaturationOptions, type ColorSaturationSpace, type ColorSpace, type ColorStringOptions, ColorSwatch, ColorSwatchOptions, ColorTemperatureAndLabel, type ColorTemperatureLabel, ColorTemperatureStringFormatOptions, type DeltaEMethod, type DeltaEOptions, ExtendedColorSwatch, GenerateColorPaletteOptions, type GrayscaleHandlingMode, HueInterpolationMode, IsColorDarkOptions, MixColorsOptions, type MixSpace, type MixType, RandomColorOptions, type ReadabilityAlgorithm, ReadabilityOptions, type WCAGReadabilityConformanceLevel, WCAGReadabilityOptions, WCAGReadabilityReport, type WCAGReadabilityTextSizeOptions, };

package/dist/src/index.js

@@ -0,0 +1,2 @@
+import { Color } from './color/color';
+export { Color, };

package/dist/src/palette/__test__/palette.test.d.ts

@@ -0,0 +1 @@
+export {};