@design-edito/tools 0.4.4 → 0.4.6

package/agnostic/colors/palette/index.test.js

@@ -0,0 +1,35 @@
+import { describe, it, expect } from 'vitest';
+import { palette } from './index.js';
+describe('palette', () => {
+    it('generates complementary palette', () => {
+        const result = palette({ r: 255, g: 0, b: 0 }, 'complementary');
+        expect(result).toHaveLength(1);
+    });
+    it('generates split-complementary palette', () => {
+        const result = palette({ r: 255, g: 0, b: 0 }, 'split-complementary');
+        expect(result).toHaveLength(2);
+    });
+    it('generates triadic palette', () => {
+        const result = palette({ r: 255, g: 0, b: 0 }, 'triadic');
+        expect(result).toHaveLength(2);
+    });
+    it('generates tetradic palette', () => {
+        const result = palette({ r: 255, g: 0, b: 0 }, 'tetradic');
+        expect(result).toHaveLength(3);
+    });
+    it('preserves color format', () => {
+        const hslColor = { h: 180, s: 50, l: 75 };
+        const result = palette(hslColor, 'complementary');
+        expect(result[0]).toHaveProperty('h');
+        expect(result[0]).toHaveProperty('s');
+        expect(result[0]).toHaveProperty('l');
+    });
+    it('generates complementary-lab palette', () => {
+        const result = palette({ r: 255, g: 0, b: 0 }, 'complementary-lab');
+        expect(result).toHaveLength(1);
+    });
+    it('generates triadic-lch palette', () => {
+        const result = palette({ r: 255, g: 0, b: 0 }, 'triadic-lch');
+        expect(result).toHaveLength(2);
+    });
+});

package/agnostic/colors/rotate/index.js

@@ -1,14 +1,41 @@
-import {
-  rotate
-} from "../../../chunks/chunk-YY3TSU22.js";
-import "../../../chunks/chunk-WGRQXVBK.js";
-import "../../../chunks/chunk-CVMYA5XK.js";
-import "../../../chunks/chunk-OBSTP7YR.js";
-import "../../../chunks/chunk-HQLRJ7XW.js";
-import "../../../chunks/chunk-DNIOWD7K.js";
-import "../../../chunks/chunk-PUQUSA6S.js";
-import "../../../chunks/chunk-OSAXBA7G.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  rotate
-};
+import { absoluteModulo } from '../../numbers/absolute-modulo/index.js';
+import { addChannel } from '../channels/index.js';
+import { viaLab, viaLch } from '../convert/index.js';
+function rotateHsl(color, degrees) {
+    return addChannel(color, 'hue', degrees);
+}
+function rotateLab(color, degrees) {
+    return viaLab(color, lab => {
+        const hue = Math.atan2(lab.b, lab.a) * (180 / Math.PI);
+        const chroma = Math.sqrt(lab.a ** 2 + lab.b ** 2);
+        const newHue = absoluteModulo(hue + degrees, 360);
+        const rad = newHue * (Math.PI / 180);
+        return {
+            ...lab,
+            a: chroma * Math.cos(rad),
+            b: chroma * Math.sin(rad)
+        };
+    });
+}
+function rotateLch(color, degrees) {
+    return viaLch(color, lch => ({
+        ...lch,
+        h: absoluteModulo(lch.h + degrees, 360)
+    }));
+}
+/**
+ * Rotates the hue of a color by a specified number of degrees.
+ *
+ * @template C - The input color type.
+ * @param {C} color - The color to rotate.
+ * @param {number} degrees - The number of degrees to rotate the hue (positive or negative).
+ * @param {RotateMethod} [method='hsl'] - The color space to use for rotation.
+ * @returns {TransformedColor<C>} The rotated color in the original format.
+ */
+export function rotate(color, degrees, method = 'hsl') {
+    switch (method) {
+        case 'hsl': return rotateHsl(color, degrees);
+        case 'lab': return rotateLab(color, degrees);
+        case 'lch': return rotateLch(color, degrees);
+    }
+}

package/agnostic/colors/rotate/index.test.js

@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest';
+import { rotate } from './index.js';
+import { toHsl } from '../convert/index.js';
+describe('rotate', () => {
+    it('rotates hue by specified degrees', () => {
+        const color = { h: 0, s: 100, l: 50 };
+        const result = rotate(color, 180);
+        const hsl = toHsl(result);
+        expect(hsl.h).toBe(180);
+    });
+    it('preserves color format', () => {
+        const rgbColor = { r: 255, g: 0, b: 0 };
+        const result = rotate(rgbColor, 180);
+        expect(result).toHaveProperty('r');
+        expect(result).toHaveProperty('g');
+        expect(result).toHaveProperty('b');
+    });
+    it('wraps hue when rotating beyond 360', () => {
+        const color = { h: 300, s: 100, l: 50 };
+        const result = rotate(color, 100);
+        const hsl = toHsl(result);
+        expect(hsl.h).toBeGreaterThanOrEqual(0);
+        expect(hsl.h).toBeLessThan(360);
+    });
+    it('uses hsl method by default', () => {
+        const color = { h: 0, s: 100, l: 50 };
+        const result1 = rotate(color, 180);
+        const result2 = rotate(color, 180, 'hsl');
+        expect(toHsl(result1).h).toBe(toHsl(result2).h);
+    });
+    it('rotates using lab method', () => {
+        const color = { r: 255, g: 0, b: 0 };
+        const result = rotate(color, 180, 'lab');
+        expect(result).toHaveProperty('r');
+        expect(result).toHaveProperty('g');
+        expect(result).toHaveProperty('b');
+    });
+    it('rotates using lch method', () => {
+        const color = { r: 255, g: 0, b: 0 };
+        const result = rotate(color, 180, 'lch');
+        expect(result).toHaveProperty('r');
+        expect(result).toHaveProperty('g');
+        expect(result).toHaveProperty('b');
+    });
+});

package/agnostic/colors/tidy/index.js

@@ -1,12 +1,80 @@
-import {
-  tidy
-} from "../../../chunks/chunk-CVMYA5XK.js";
-import "../../../chunks/chunk-OBSTP7YR.js";
-import "../../../chunks/chunk-HQLRJ7XW.js";
-import "../../../chunks/chunk-DNIOWD7K.js";
-import "../../../chunks/chunk-PUQUSA6S.js";
-import "../../../chunks/chunk-OSAXBA7G.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  tidy
-};
+import { isRgb, isHsl, isHsb, isCmyk, isXyz, isLab, isLch, isCssColor, isHex } from '../typechecks/index.js';
+import { clamp } from '../../numbers/clamp/index.js';
+import { absoluteModulo } from '../../numbers/absolute-modulo/index.js';
+import { toRgb, toHex } from '../convert/index.js';
+import { unknownToString } from '../../errors/unknown-to-string/index.js';
+/**
+ * Clamps and normalizes a color's channel values to their valid ranges.
+ *
+ * @template C - The input color type.
+ * @param {C} color - The color to tidy.
+ * @returns {TransformedColor<C>} The color with all channels clamped to valid ranges, in the original format.
+ * @throws {Error} If the color format is invalid or unsupported.
+ */
+export function tidy(color) {
+    const _color = color;
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    if (isRgb(_color))
+        return {
+            r: clamp(_color.r, 0, 255),
+            g: clamp(_color.g, 0, 255),
+            b: clamp(_color.b, 0, 255),
+            a: clamp(_color.a ?? 1, 0, 1)
+        };
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    if (isHsl(_color))
+        return {
+            h: absoluteModulo(_color.h, 360),
+            s: clamp(_color.s, 0, 100),
+            l: clamp(_color.l, 0, 100),
+            a: clamp(_color.a ?? 1, 0, 1)
+        };
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    if (isHsb(_color))
+        return {
+            h: absoluteModulo(_color.h, 360),
+            s: clamp(_color.s, 0, 100),
+            b: clamp(_color.b, 0, 100),
+            a: clamp(_color.a ?? 1, 0, 1)
+        };
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    if (isCmyk(_color))
+        return {
+            c: clamp(_color.c, 0, 100),
+            m: clamp(_color.m, 0, 100),
+            y: clamp(_color.y, 0, 100),
+            k: clamp(_color.k, 0, 100),
+            a: clamp(_color.a ?? 1, 0, 1)
+        };
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    if (isXyz(_color))
+        return {
+            x: _color.x,
+            y: _color.y,
+            z: _color.z,
+            a: clamp(_color.a ?? 1, 0, 1)
+        };
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    if (isLab(_color))
+        return {
+            l: clamp(_color.l, 0, 100),
+            a: _color.a,
+            b: _color.b,
+            al: clamp(_color.al ?? 1, 0, 1)
+        };
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    if (isLch(_color))
+        return {
+            l: clamp(_color.l, 0, 100),
+            c: Math.max(0, _color.c),
+            h: clamp(_color.h, 0, 360),
+            a: clamp(_color.a ?? 1, 0, 1)
+        };
+    if (isCssColor(_color))
+        return tidy(toRgb(_color));
+    if (isHex(_color))
+        return toHex(tidy(toRgb(_color)));
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const _typecheck = true;
+    throw new Error(`Invalid color input: ${unknownToString(_color)}`);
+}

package/agnostic/colors/tidy/index.test.js

@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest';
+import { tidy } from './index.js';
+describe('tidy', () => {
+    it('clamps RGB values to valid range', () => {
+        const result = tidy({ r: 300, g: -10, b: 128 });
+        expect(result).toMatchObject({ r: 255, g: 0, b: 128 });
+    });
+    it('clamps alpha to 0-1 range', () => {
+        const result = tidy({ r: 128, g: 128, b: 128, a: 2 });
+        expect(result).toMatchObject({ a: 1 });
+    });
+    it('preserves valid RGB colors', () => {
+        const color = { r: 128, g: 128, b: 128, a: 0.5 };
+        const result = tidy(color);
+        expect(result).toEqual({ r: 128, g: 128, b: 128, a: 0.5 });
+    });
+    it('clamps HSL values to valid range', () => {
+        const result = tidy({ h: 450, s: 150, l: -10 });
+        expect(result).toMatchObject({ h: 90, s: 100, l: 0 });
+    });
+    it('wraps hue to 0-360 range', () => {
+        const result = tidy({ h: -30, s: 50, l: 50 });
+        expect(result).toMatchObject({ h: 330, s: 50, l: 50 });
+    });
+    it('clamps HSB values to valid range', () => {
+        const result = tidy({ h: 450, s: 150, b: -10 });
+        expect(result).toMatchObject({ h: 90, s: 100, b: 0 });
+    });
+    it('clamps CMYK values to valid range', () => {
+        const result = tidy({ c: 150, m: -10, y: 50, k: 50 });
+        expect(result).toMatchObject({ c: 100, m: 0, y: 50, k: 50 });
+    });
+    it('preserves color format', () => {
+        const hslColor = { h: 180, s: 50, l: 75 };
+        const result = tidy(hslColor);
+        expect(result).toHaveProperty('h');
+        expect(result).toHaveProperty('s');
+        expect(result).toHaveProperty('l');
+    });
+    it('tidies hex colors', () => {
+        const result = tidy('#ff0000');
+        expect(typeof result).toBe('string');
+        expect(result).toMatch(/^#/);
+    });
+});

package/agnostic/colors/typechecks/index.js

@@ -1,26 +1,197 @@
-import {
-  isCmyk,
-  isColor,
-  isCssColor,
-  isHex,
-  isHsb,
-  isHsl,
-  isLab,
-  isLch,
-  isRgb,
-  isXyz
-} from "../../../chunks/chunk-OBSTP7YR.js";
-import "../../../chunks/chunk-HQLRJ7XW.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  isCmyk,
-  isColor,
-  isCssColor,
-  isHex,
-  isHsb,
-  isHsl,
-  isLab,
-  isLch,
-  isRgb,
-  isXyz
+import { isNonNullObject } from '../../objects/is-object/index.js';
+import { cssColors } from '../cssColorsMap.js';
+/**
+ * Type guard to check if a value is a valid hexadecimal color string.
+ *
+ * @param {unknown} color - The value to check.
+ * @returns {color is Hex} True if the value is a valid hex color, false otherwise.
+ */
+export const isHex = (color) => {
+    if (typeof color !== 'string')
+        return false;
+    if (!color.startsWith('#'))
+        return false;
+    const withoutHash = color.slice(1);
+    const withoutHashLength = withoutHash.length;
+    const allowedLengths = [3, 4, 6, 8];
+    if (!allowedLengths.includes(withoutHashLength))
+        return false;
+    return /^[0-9a-f]+$/igm.test(withoutHash);
+};
+/**
+ * Type guard to check if a value is a valid RGBA color object.
+ *
+ * @param {unknown} color - The value to check.
+ * @returns {color is Rgba} True if the value is a valid RGBA color, false otherwise.
+ */
+export const isRgb = (color) => {
+    if (!isNonNullObject(color))
+        return false;
+    const { r, g, b, a } = color;
+    if (typeof r !== 'number')
+        return false;
+    if (typeof g !== 'number')
+        return false;
+    if (typeof b !== 'number')
+        return false;
+    if (a !== undefined && typeof a !== 'number')
+        return false;
+    return true;
+};
+/**
+ * Type guard to check if a value is a valid HSLA color object.
+ *
+ * @param {unknown} color - The value to check.
+ * @returns {color is Hsla} True if the value is a valid HSLA color, false otherwise.
+ */
+export const isHsl = (color) => {
+    if (!isNonNullObject(color))
+        return false;
+    const { h, s, l, a } = color;
+    if (typeof h !== 'number')
+        return false;
+    if (typeof s !== 'number')
+        return false;
+    if (typeof l !== 'number')
+        return false;
+    if (a !== undefined && typeof a !== 'number')
+        return false;
+    return true;
+};
+/**
+ * Type guard to check if a value is a valid HSBA color object.
+ *
+ * @param {unknown} color - The value to check.
+ * @returns {color is Hsba} True if the value is a valid HSBA color, false otherwise.
+ */
+export const isHsb = (color) => {
+    if (!isNonNullObject(color))
+        return false;
+    const { h, s, b, a } = color;
+    if (typeof h !== 'number')
+        return false;
+    if (typeof s !== 'number')
+        return false;
+    if (typeof b !== 'number')
+        return false;
+    if (a !== undefined && typeof a !== 'number')
+        return false;
+    return true;
+};
+/**
+ * Type guard to check if a value is a valid CIELAB color object.
+ *
+ * @param {unknown} color - The value to check.
+ * @returns {color is Laba} True if the value is a valid CIELAB color, false otherwise.
+ */
+export const isLab = (color) => {
+    if (!isNonNullObject(color))
+        return false;
+    const { l, a, b, al } = color;
+    if (typeof l !== 'number')
+        return false;
+    if (typeof a !== 'number')
+        return false;
+    if (typeof b !== 'number')
+        return false;
+    if (al !== undefined && typeof al !== 'number')
+        return false;
+    return true;
+};
+/**
+ * Type guard to check if a value is a valid CIELCh color object.
+ *
+ * @param {unknown} color - The value to check.
+ * @returns {color is Lcha} True if the value is a valid CIELCh color, false otherwise.
+ */
+export const isLch = (color) => {
+    if (!isNonNullObject(color))
+        return false;
+    const { l, c, h, a } = color;
+    if (typeof l !== 'number')
+        return false;
+    if (typeof c !== 'number')
+        return false;
+    if (typeof h !== 'number')
+        return false;
+    if (a !== undefined && typeof a !== 'number')
+        return false;
+    return true;
+};
+/**
+ * Type guard to check if a value is a valid CMYK color object.
+ *
+ * @param {unknown} color - The value to check.
+ * @returns {color is Cmyka} True if the value is a valid CMYK color, false otherwise.
+ */
+export const isCmyk = (color) => {
+    if (!isNonNullObject(color))
+        return false;
+    const { c, m, y, k, a } = color;
+    if (typeof c !== 'number')
+        return false;
+    if (typeof m !== 'number')
+        return false;
+    if (typeof y !== 'number')
+        return false;
+    if (typeof k !== 'number')
+        return false;
+    if (a !== undefined && typeof a !== 'number')
+        return false;
+    return true;
+};
+/**
+ * Type guard to check if a value is a valid CIE XYZ color object.
+ *
+ * @param {unknown} color - The value to check.
+ * @returns {color is Xyza} True if the value is a valid CIE XYZ color, false otherwise.
+ */
+export const isXyz = (color) => {
+    if (!isNonNullObject(color))
+        return false;
+    const { x, y, z, a } = color;
+    if (typeof x !== 'number')
+        return false;
+    if (typeof y !== 'number')
+        return false;
+    if (typeof z !== 'number')
+        return false;
+    if (a !== undefined && typeof a !== 'number')
+        return false;
+    return true;
+};
+/**
+ * Type guard to check if a value is a valid CSS named color.
+ *
+ * @param {unknown} color - The value to check.
+ * @returns {color is CssColor} True if the value is a valid CSS named color, false otherwise.
+ */
+export const isCssColor = (color) => typeof color === 'string'
+    && cssColors[color] !== undefined;
+/**
+ * Type guard to check if a value is any valid color format.
+ *
+ * @param {unknown} color - The value to check.
+ * @returns {color is Color} True if the value is a valid color in any supported format, false otherwise.
+ */
+export const isColor = (color) => {
+    if (isHex(color))
+        return true;
+    if (isCssColor(color))
+        return true;
+    if (isRgb(color))
+        return true;
+    if (isHsl(color))
+        return true;
+    if (isHsb(color))
+        return true;
+    if (isCmyk(color))
+        return true;
+    if (isXyz(color))
+        return true;
+    if (isLab(color))
+        return true;
+    if (isLch(color))
+        return true;
+    return false;
 };

package/agnostic/colors/typechecks/index.test.js

@@ -0,0 +1,113 @@
+import { describe, it, expect } from 'vitest';
+import { isHex, isRgb, isHsl, isHsb, isCmyk, isXyz, isLab, isLch, isCssColor, isColor } from './index.js';
+describe('isHex', () => {
+    it('returns true for valid hex colors', () => {
+        expect(isHex('#ff0000')).toBe(true);
+        expect(isHex('#f00')).toBe(true);
+        expect(isHex('#ff0000ff')).toBe(true);
+        expect(isHex('#f00f')).toBe(true);
+    });
+    it('returns false for invalid hex colors', () => {
+        expect(isHex('ff0000')).toBe(false);
+        expect(isHex('#gg0000')).toBe(false);
+        expect(isHex('#ff')).toBe(false);
+        expect(isHex(123)).toBe(false);
+    });
+});
+describe('isRgb', () => {
+    it('returns true for valid RGB colors', () => {
+        expect(isRgb({ r: 255, g: 128, b: 64 })).toBe(true);
+        expect(isRgb({ r: 255, g: 128, b: 64, a: 0.5 })).toBe(true);
+    });
+    it('returns false for invalid RGB colors', () => {
+        expect(isRgb({ r: 255, g: 128 })).toBe(false);
+        expect(isRgb({ r: '255', g: 128, b: 64 })).toBe(false);
+        expect(isRgb(null)).toBe(false);
+    });
+});
+describe('isHsl', () => {
+    it('returns true for valid HSL colors', () => {
+        expect(isHsl({ h: 180, s: 50, l: 75 })).toBe(true);
+        expect(isHsl({ h: 180, s: 50, l: 75, a: 0.5 })).toBe(true);
+    });
+    it('returns false for invalid HSL colors', () => {
+        expect(isHsl({ h: 180, s: 50 })).toBe(false);
+        expect(isHsl({ h: '180', s: 50, l: 75 })).toBe(false);
+        expect(isHsl(null)).toBe(false);
+    });
+});
+describe('isHsb', () => {
+    it('returns true for valid HSB colors', () => {
+        expect(isHsb({ h: 180, s: 50, b: 75 })).toBe(true);
+        expect(isHsb({ h: 180, s: 50, b: 75, a: 0.5 })).toBe(true);
+    });
+    it('returns false for invalid HSB colors', () => {
+        expect(isHsb({ h: 180, s: 50 })).toBe(false);
+        expect(isHsb({ h: '180', s: 50, b: 75 })).toBe(false);
+    });
+});
+describe('isCmyk', () => {
+    it('returns true for valid CMYK colors', () => {
+        expect(isCmyk({ c: 50, m: 50, y: 50, k: 50 })).toBe(true);
+        expect(isCmyk({ c: 50, m: 50, y: 50, k: 50, a: 0.5 })).toBe(true);
+    });
+    it('returns false for invalid CMYK colors', () => {
+        expect(isCmyk({ c: 50, m: 50, y: 50 })).toBe(false);
+        expect(isCmyk({ c: '50', m: 50, y: 50, k: 50 })).toBe(false);
+    });
+});
+describe('isXyz', () => {
+    it('returns true for valid XYZ colors', () => {
+        expect(isXyz({ x: 50, y: 50, z: 50 })).toBe(true);
+        expect(isXyz({ x: 50, y: 50, z: 50, a: 0.5 })).toBe(true);
+    });
+    it('returns false for invalid XYZ colors', () => {
+        expect(isXyz({ x: 50, y: 50 })).toBe(false);
+        expect(isXyz({ x: '50', y: 50, z: 50 })).toBe(false);
+    });
+});
+describe('isLab', () => {
+    it('returns true for valid Lab colors', () => {
+        expect(isLab({ l: 50, a: 0, b: 0 })).toBe(true);
+        expect(isLab({ l: 50, a: 0, b: 0, al: 0.5 })).toBe(true);
+    });
+    it('returns false for invalid Lab colors', () => {
+        expect(isLab({ l: 50, a: 0 })).toBe(false);
+        expect(isLab({ l: '50', a: 0, b: 0 })).toBe(false);
+    });
+});
+describe('isLch', () => {
+    it('returns true for valid LCH colors', () => {
+        expect(isLch({ l: 50, c: 50, h: 180 })).toBe(true);
+        expect(isLch({ l: 50, c: 50, h: 180, a: 0.5 })).toBe(true);
+    });
+    it('returns false for invalid LCH colors', () => {
+        expect(isLch({ l: 50, c: 50 })).toBe(false);
+        expect(isLch({ l: '50', c: 50, h: 180 })).toBe(false);
+    });
+});
+describe('isCssColor', () => {
+    it('returns true for valid CSS color names', () => {
+        expect(isCssColor('red')).toBe(true);
+        expect(isCssColor('blue')).toBe(true);
+    });
+    it('returns false for invalid CSS color names', () => {
+        expect(isCssColor('notacolor')).toBe(false);
+        expect(isCssColor('#ff0000')).toBe(false);
+        expect(isCssColor(123)).toBe(false);
+    });
+});
+describe('isColor', () => {
+    it('returns true for any valid color format', () => {
+        expect(isColor('#ff0000')).toBe(true);
+        expect(isColor({ r: 255, g: 0, b: 0 })).toBe(true);
+        expect(isColor({ h: 0, s: 100, l: 50 })).toBe(true);
+        expect(isColor('red')).toBe(true);
+    });
+    it('returns false for invalid colors', () => {
+        expect(isColor('notacolor')).toBe(false);
+        expect(isColor(123)).toBe(false);
+        expect(isColor(null)).toBe(false);
+        expect(isColor({ r: 255 })).toBe(false);
+    });
+});

package/agnostic/colors/types.js

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