@design-edito/tools 0.4.4 → 0.4.6

package/agnostic/arrays/shuffle/index.js

@@ -1,14 +1,16 @@
-import "../../../chunks/chunk-WSFCRVEQ.js";
-
-// src/agnostic/arrays/shuffle/index.ts
-function shuffle(array) {
-  const shuffled = [...array];
-  for (let i = shuffled.length - 1; i > 0; i--) {
-    const j = Math.floor(Math.random() * (i + 1));
-    [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
-  }
-  return shuffled;
+/**
+ * Shuffles an array using the Fisher-Yates algorithm.
+ *
+ * Creates a new array with the same elements in random order. The original array is not modified.
+ *
+ * @param array - The array to shuffle.
+ * @returns A new array with shuffled elements.
+ */
+export function shuffle(array) {
+    const shuffled = [...array];
+    for (let i = shuffled.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+    }
+    return shuffled;
 }
-export {
-  shuffle
-};

package/agnostic/arrays/shuffle/index.test.js

@@ -0,0 +1,14 @@
+import { describe, it, expect } from 'vitest';
+import { shuffle } from './index.js';
+describe('shuffle', () => {
+    it('shuffles and keeps the same length', () => {
+        const source = [0, 1, 2, 3, 4];
+        const shuffled = shuffle(source);
+        expect(shuffled).toHaveLength(5);
+        expect(shuffled).toContain(0);
+        expect(shuffled).toContain(1);
+        expect(shuffled).toContain(2);
+        expect(shuffled).toContain(3);
+        expect(shuffled).toContain(4);
+    });
+});

package/agnostic/booleans/is-falsy/index.js

@@ -1,12 +1,26 @@
-import {
-  falsyValues,
-  isFalsy,
-  isNotFalsy
-} from "../../../chunks/chunk-QXAJXTXV.js";
-import "../../../chunks/chunk-HC6ZOHCS.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  falsyValues,
-  isFalsy,
-  isNotFalsy
-};
+import { nullishValues } from '../../misc/is-nullish/index.js';
+/** Array containing all falsy values for comparison. */
+const falsyValues = [...nullishValues, false, '', 0, -0, NaN];
+if (typeof BigInt === 'function')
+    falsyValues.push(BigInt(0));
+export { falsyValues };
+/**
+ * Type guard to check if a value is falsy.
+ *
+ * Checks if the value is one of: null, undefined, false, empty string, 0, -0, NaN, or 0n.
+ *
+ * @param val - The value to check.
+ * @returns `true` if the value is falsy, `false` otherwise.
+ */
+export function isFalsy(val) {
+    return falsyValues.includes(val);
+}
+/**
+ * Type guard to check if a value is not falsy.
+ *
+ * @param val - The value to check.
+ * @returns `true` if the value is not falsy, `false` otherwise.
+ */
+export function isNotFalsy(val) {
+    return !isFalsy(val);
+}

package/agnostic/booleans/is-falsy/index.test.js

@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest';
+import { isFalsy, isNotFalsy } from './index.js';
+describe('is-falsy', () => {
+    it('returns true on all falsy values', () => {
+        expect(isFalsy(null)).toBe(true);
+        expect(isFalsy(undefined)).toBe(true);
+        expect(isFalsy(false)).toBe(true);
+        expect(isFalsy('')).toBe(true);
+        expect(isFalsy(0)).toBe(true);
+        expect(isFalsy(-0)).toBe(true);
+        expect(isFalsy(NaN)).toBe(true);
+        expect(isFalsy(0n)).toBe(true);
+    });
+});
+describe('is-not-falsy', () => {
+    it('returns false on all falsy values', () => {
+        expect(isNotFalsy(null)).toBe(false);
+        expect(isNotFalsy(undefined)).toBe(false);
+        expect(isNotFalsy(false)).toBe(false);
+        expect(isNotFalsy('')).toBe(false);
+        expect(isNotFalsy(0)).toBe(false);
+        expect(isNotFalsy(-0)).toBe(false);
+        expect(isNotFalsy(NaN)).toBe(false);
+        expect(isNotFalsy(0n)).toBe(false);
+    });
+});

package/agnostic/colors/channels/index.js

@@ -1,19 +1,145 @@
-import {
-  addChannel,
-  getChannel,
-  multChannel,
-  setChannel
-} from "../../../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 {
-  addChannel,
-  getChannel,
-  multChannel,
-  setChannel
-};
+import { clamp } from '../../numbers/clamp/index.js';
+import { absoluteModulo } from '../../numbers/absolute-modulo/index.js';
+import { toRgb, toHsl, toHsb, toCmyk, toXyz, toLab, toLch, viaRgb, viaHsl, viaHsb, viaCmyk, viaXyz, viaLab, viaLch } from '../convert/index.js';
+/* * * * * * * * * * * * * * * * * *
+ * Set channel
+ * * * * * * * * * * * * * * * * * */
+/**
+ * Sets a specific color channel to an absolute value.
+ *
+ * @template C - The input color type.
+ * @param {C} color - The color to modify.
+ * @param {Channel} channel - The channel to set.
+ * @param {number} value - The new value for the channel.
+ * @returns {TransformedColor<C>} The color with the updated channel, in the original format.
+ */
+export function setChannel(color, channel, value) {
+    switch (channel) {
+        case 'red': return viaRgb(color, rgb => ({ ...rgb, r: clamp(value, 0, 255) }));
+        case 'green': return viaRgb(color, rgb => ({ ...rgb, g: clamp(value, 0, 255) }));
+        case 'blue': return viaRgb(color, rgb => ({ ...rgb, b: clamp(value, 0, 255) }));
+        case 'hue': return viaHsl(color, hsl => ({ ...hsl, h: absoluteModulo(value, 360) }));
+        case 'saturation': return viaHsl(color, hsl => ({ ...hsl, s: clamp(value, 0, 100) }));
+        case 'lightness': return viaHsl(color, hsl => ({ ...hsl, l: clamp(value, 0, 100) }));
+        case 'brightness': return viaHsb(color, hsb => ({ ...hsb, b: clamp(value, 0, 100) }));
+        case 'alpha': return viaRgb(color, rgb => ({ ...rgb, a: clamp(value, 0, 1) }));
+        case 'cyan': return viaCmyk(color, cmyk => ({ ...cmyk, c: clamp(value, 0, 100) }));
+        case 'magenta': return viaCmyk(color, cmyk => ({ ...cmyk, m: clamp(value, 0, 100) }));
+        case 'yellow': return viaCmyk(color, cmyk => ({ ...cmyk, y: clamp(value, 0, 100) }));
+        case 'black': return viaCmyk(color, cmyk => ({ ...cmyk, k: clamp(value, 0, 100) }));
+        case 'x': return viaXyz(color, xyz => ({ ...xyz, x: value }));
+        case 'y': return viaXyz(color, xyz => ({ ...xyz, y: value }));
+        case 'z': return viaXyz(color, xyz => ({ ...xyz, z: value }));
+        case 'lightnessLab': return viaLab(color, lab => ({ ...lab, a: clamp(value, 0, 100) }));
+        case 'aLab': return viaLab(color, lab => ({ ...lab, a: value }));
+        case 'bLab': return viaLab(color, lab => ({ ...lab, b: value }));
+        case 'chroma': return viaLch(color, lch => ({ ...lch, c: Math.max(0, value) }));
+        case 'hueLch': return viaLch(color, lch => ({ ...lch, h: clamp(value, 0, 360) }));
+    }
+}
+/* * * * * * * * * * * * * * * * * *
+ * Get channel
+ * * * * * * * * * * * * * * * * * */
+/**
+ * Gets the value of a specific color channel.
+ *
+ * @param {Color} color - The color to read from.
+ * @param {Channel} channel - The channel to retrieve.
+ * @returns {number} The value of the specified channel.
+ */
+export function getChannel(color, channel) {
+    switch (channel) {
+        case 'red': return toRgb(color).r;
+        case 'green': return toRgb(color).g;
+        case 'blue': return toRgb(color).b;
+        case 'hue': return toHsl(color).h;
+        case 'saturation': return toHsl(color).s;
+        case 'lightness': return toHsl(color).l;
+        case 'brightness': return toHsb(color).b;
+        case 'alpha': return toRgb(color).a ?? 1;
+        case 'cyan': return toCmyk(color).c;
+        case 'magenta': return toCmyk(color).m;
+        case 'yellow': return toCmyk(color).y;
+        case 'black': return toCmyk(color).k;
+        case 'x': return toXyz(color).x;
+        case 'y': return toXyz(color).y;
+        case 'z': return toXyz(color).z;
+        case 'lightnessLab': return toLab(color).l;
+        case 'aLab': return toLab(color).a;
+        case 'bLab': return toLab(color).b;
+        case 'chroma': return toLch(color).c;
+        case 'hueLch': return toLch(color).h;
+    }
+}
+/* * * * * * * * * * * * * * * * * *
+ * Add channel
+ * * * * * * * * * * * * * * * * * */
+/**
+ * Adds a value to a specific color channel.
+ *
+ * @template C - The input color type.
+ * @param {C} color - The color to modify.
+ * @param {Channel} channel - The channel to modify.
+ * @param {number} amount - The amount to add to the channel.
+ * @returns {TransformedColor<C>} The color with the updated channel, in the original format.
+ */
+export function addChannel(color, channel, amount) {
+    switch (channel) {
+        case 'red': return viaRgb(color, rgb => ({ ...rgb, r: clamp(rgb.r + amount, 0, 255) }));
+        case 'green': return viaRgb(color, rgb => ({ ...rgb, g: clamp(rgb.g + amount, 0, 255) }));
+        case 'blue': return viaRgb(color, rgb => ({ ...rgb, b: clamp(rgb.b + amount, 0, 255) }));
+        case 'hue': return viaHsl(color, hsl => ({ ...hsl, h: absoluteModulo(hsl.h + amount, 360) }));
+        case 'saturation': return viaHsl(color, hsl => ({ ...hsl, s: clamp(hsl.s + amount, 0, 100) }));
+        case 'lightness': return viaHsl(color, hsl => ({ ...hsl, l: clamp(hsl.l + amount, 0, 100) }));
+        case 'brightness': return viaHsb(color, hsb => ({ ...hsb, b: clamp(hsb.b + amount, 0, 100) }));
+        case 'alpha': return viaRgb(color, rgb => ({ ...rgb, a: clamp(rgb.a ?? 1 + amount, 0, 1) }));
+        case 'cyan': return viaCmyk(color, cmyk => ({ ...cmyk, c: clamp(cmyk.c + amount, 0, 100) }));
+        case 'magenta': return viaCmyk(color, cmyk => ({ ...cmyk, m: clamp(cmyk.m + amount, 0, 100) }));
+        case 'yellow': return viaCmyk(color, cmyk => ({ ...cmyk, y: clamp(cmyk.y + amount, 0, 100) }));
+        case 'black': return viaCmyk(color, cmyk => ({ ...cmyk, k: clamp(cmyk.k + amount, 0, 100) }));
+        case 'x': return viaXyz(color, xyz => ({ ...xyz, x: xyz.x + amount }));
+        case 'y': return viaXyz(color, xyz => ({ ...xyz, y: xyz.y + amount }));
+        case 'z': return viaXyz(color, xyz => ({ ...xyz, z: xyz.z + amount }));
+        case 'lightnessLab': return viaLab(color, lab => ({ ...lab, l: clamp(lab.l + amount, 0, 100) }));
+        case 'aLab': return viaLab(color, lab => ({ ...lab, a: lab.a + amount }));
+        case 'bLab': return viaLab(color, lab => ({ ...lab, b: lab.b + amount }));
+        case 'chroma': return viaLch(color, lch => ({ ...lch, c: Math.max(0, lch.c + amount) }));
+        case 'hueLch': return viaLch(color, lch => ({ ...lch, h: clamp(lch.h + amount, 0, 360) }));
+    }
+}
+/* * * * * * * * * * * * * * * * * *
+ * Mult channel
+ * * * * * * * * * * * * * * * * * */
+/**
+ * Multiplies a specific color channel by a factor.
+ *
+ * @template C - The input color type.
+ * @param {C} color - The color to modify.
+ * @param {Channel} channel - The channel to modify.
+ * @param {number} factor - The multiplication factor.
+ * @returns {TransformedColor<C>} The color with the updated channel, in the original format.
+ */
+export function multChannel(color, channel, factor) {
+    switch (channel) {
+        case 'red': return viaRgb(color, rgb => ({ ...rgb, r: clamp(rgb.r * factor, 0, 255) }));
+        case 'green': return viaRgb(color, rgb => ({ ...rgb, g: clamp(rgb.g * factor, 0, 255) }));
+        case 'blue': return viaRgb(color, rgb => ({ ...rgb, b: clamp(rgb.b * factor, 0, 255) }));
+        case 'hue': return viaHsl(color, hsl => ({ ...hsl, h: absoluteModulo(hsl.h * factor, 360) }));
+        case 'saturation': return viaHsl(color, hsl => ({ ...hsl, s: clamp(hsl.s * factor, 0, 100) }));
+        case 'lightness': return viaHsl(color, hsl => ({ ...hsl, l: clamp(hsl.l * factor, 0, 100) }));
+        case 'brightness': return viaHsb(color, hsb => ({ ...hsb, b: clamp(hsb.b * factor, 0, 100) }));
+        case 'alpha': return viaRgb(color, rgb => ({ ...rgb, a: clamp(rgb.a ?? 1 * factor, 0, 1) }));
+        case 'cyan': return viaCmyk(color, cmyk => ({ ...cmyk, c: clamp(cmyk.c * factor, 0, 100) }));
+        case 'magenta': return viaCmyk(color, cmyk => ({ ...cmyk, m: clamp(cmyk.m * factor, 0, 100) }));
+        case 'yellow': return viaCmyk(color, cmyk => ({ ...cmyk, y: clamp(cmyk.y * factor, 0, 100) }));
+        case 'black': return viaCmyk(color, cmyk => ({ ...cmyk, k: clamp(cmyk.k * factor, 0, 100) }));
+        case 'x': return viaXyz(color, xyz => ({ ...xyz, x: xyz.x * factor }));
+        case 'y': return viaXyz(color, xyz => ({ ...xyz, y: xyz.y * factor }));
+        case 'z': return viaXyz(color, xyz => ({ ...xyz, z: xyz.z * factor }));
+        case 'lightnessLab': return viaLab(color, lab => ({ ...lab, l: clamp(lab.l * factor, 0, 100) }));
+        case 'aLab': return viaLab(color, lab => ({ ...lab, a: lab.a * factor }));
+        case 'bLab': return viaLab(color, lab => ({ ...lab, b: lab.b * factor }));
+        case 'chroma': return viaLch(color, lch => ({ ...lch, c: Math.max(0, lch.c * factor) }));
+        case 'hueLch': return viaLch(color, lch => ({ ...lch, h: clamp(lch.h * factor, 0, 360) }));
+    }
+}

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

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest';
+import { getChannel, setChannel, addChannel, multChannel } from './index.js';
+describe('getChannel', () => {
+    it('gets RGB channels', () => {
+        expect(getChannel({ r: 255, g: 128, b: 64 }, 'red')).toBe(255);
+        expect(getChannel({ r: 255, g: 128, b: 64 }, 'green')).toBe(128);
+        expect(getChannel({ r: 255, g: 128, b: 64 }, 'blue')).toBe(64);
+    });
+    it('gets HSL channels', () => {
+        expect(getChannel({ h: 180, s: 50, l: 75 }, 'hue')).toBe(180);
+        expect(getChannel({ h: 180, s: 50, l: 75 }, 'saturation')).toBe(50);
+        expect(getChannel({ h: 180, s: 50, l: 75 }, 'lightness')).toBe(75);
+    });
+    it('gets alpha channel', () => {
+        expect(getChannel({ r: 255, g: 128, b: 64, a: 0.5 }, 'alpha')).toBe(0.5);
+        expect(getChannel({ r: 255, g: 128, b: 64 }, 'alpha')).toBe(1);
+    });
+});
+describe('setChannel', () => {
+    it('sets RGB channels', () => {
+        const result = setChannel({ r: 100, g: 100, b: 100 }, 'red', 255);
+        expect(result).toMatchObject({ r: 255, g: 100, b: 100 });
+    });
+    it('clamps RGB channels to valid range', () => {
+        const result = setChannel({ r: 100, g: 100, b: 100 }, 'red', 500);
+        expect(result).toMatchObject({ r: 255, g: 100, b: 100 });
+    });
+    it('sets HSL channels', () => {
+        const result = setChannel({ h: 0, s: 50, l: 50 }, 'hue', 180);
+        expect(result).toMatchObject({ h: 180, s: 50, l: 50 });
+    });
+    it('wraps hue channel', () => {
+        const result = setChannel({ h: 0, s: 50, l: 50 }, 'hue', 450);
+        expect(result).toMatchObject({ h: 90, s: 50, l: 50 });
+    });
+});
+describe('addChannel', () => {
+    it('adds to RGB channels', () => {
+        const result = addChannel({ r: 100, g: 100, b: 100 }, 'red', 50);
+        expect(result).toMatchObject({ r: 150, g: 100, b: 100 });
+    });
+    it('clamps RGB channels when adding', () => {
+        const result = addChannel({ r: 200, g: 100, b: 100 }, 'red', 100);
+        expect(result).toMatchObject({ r: 255, g: 100, b: 100 });
+    });
+    it('adds to hue channel with wrapping', () => {
+        const result = addChannel({ h: 350, s: 50, l: 50 }, 'hue', 30);
+        expect(result).toMatchObject({ h: 20, s: 50, l: 50 });
+    });
+});
+describe('multChannel', () => {
+    it('multiplies RGB channels', () => {
+        const result = multChannel({ r: 100, g: 100, b: 100 }, 'red', 2);
+        expect(result).toMatchObject({ r: 200, g: 100, b: 100 });
+    });
+    it('clamps RGB channels when multiplying', () => {
+        const result = multChannel({ r: 200, g: 100, b: 100 }, 'red', 2);
+        expect(result).toMatchObject({ r: 255, g: 100, b: 100 });
+    });
+    it('multiplies hue channel with wrapping', () => {
+        const result = multChannel({ h: 100, s: 50, l: 50 }, 'hue', 2);
+        expect(result).toMatchObject({ h: 200, s: 50, l: 50 });
+    });
+});

package/agnostic/colors/contrast/index.js

@@ -1,33 +1,26 @@
-import {
-  luminance
-} from "../../../chunks/chunk-E2ZY3SEW.js";
-import {
-  toRgb
-} 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";
-
-// src/agnostic/colors/contrast/index.ts
+import { luminance } from '../luminance/index.js';
+import { toRgb } from '../convert/index.js';
 function contrastWcag(c1, c2) {
-  const L1 = luminance(c1, "rgb");
-  const L2 = luminance(c2, "rgb");
-  const lighter = Math.max(L1, L2);
-  const darker = Math.min(L1, L2);
-  const numerator = lighter + 0.05;
-  const denominator = darker + 0.05;
-  const ratio = numerator / denominator;
-  return ratio;
+    const L1 = luminance(c1, 'rgb');
+    const L2 = luminance(c2, 'rgb');
+    const lighter = Math.max(L1, L2);
+    const darker = Math.min(L1, L2);
+    const numerator = lighter + 0.05;
+    const denominator = darker + 0.05;
+    const ratio = numerator / denominator;
+    return ratio;
 }
-function contrast(c1, c2, method = "wcag") {
-  switch (method) {
-    case "wcag":
-      return contrastWcag(toRgb(c1), toRgb(c2));
-  }
+// [WIP] maybe contrast weber, michelson, rms, etc...
+/**
+ * Calculates the contrast ratio between two colors using the specified method.
+ *
+ * @param {Color} c1 - The first color.
+ * @param {Color} c2 - The second color.
+ * @param {ContrastMethod} [method='wcag'] - The calculation method to use.
+ * @returns {number} The contrast ratio. For WCAG, values range from 1 (no contrast) to 21 (maximum contrast).
+ */
+export function contrast(c1, c2, method = 'wcag') {
+    switch (method) {
+        case 'wcag': return contrastWcag(toRgb(c1), toRgb(c2));
+    }
 }
-export {
-  contrast
-};

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

@@ -0,0 +1,21 @@
+import { describe, it, expect } from 'vitest';
+import { contrast } from './index.js';
+describe('contrast', () => {
+    it('calculates contrast between white and black', () => {
+        const result = contrast({ r: 255, g: 255, b: 255 }, { r: 0, g: 0, b: 0 });
+        expect(result).toBeGreaterThan(20);
+    });
+    it('calculates contrast between similar colors', () => {
+        const result = contrast({ r: 200, g: 200, b: 200 }, { r: 210, g: 210, b: 210 });
+        expect(result).toBeLessThan(2);
+    });
+    it('uses wcag method by default', () => {
+        const result1 = contrast({ r: 255, g: 0, b: 0 }, { r: 0, g: 255, b: 0 });
+        const result2 = contrast({ r: 255, g: 0, b: 0 }, { r: 0, g: 255, b: 0 }, 'wcag');
+        expect(result1).toBe(result2);
+    });
+    it('returns value greater than 1 for any two colors', () => {
+        const result = contrast({ r: 100, g: 100, b: 100 }, { r: 150, g: 150, b: 150 });
+        expect(result).toBeGreaterThanOrEqual(1);
+    });
+});