@auaust/jaune 0.0.3 → 0.0.5

package/package.json

@@ -2,7 +2,7 @@
   "name": "@auaust/jaune",
   "license": "GPL-3.0-only",
   "type": "module",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "publishConfig": {
     "access": "public"
   },
@@ -13,13 +13,13 @@
     "url": "https://auaust.ch"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.28.1",
-    "@vitest/coverage-istanbul": "^2.1.9",
-    "rimraf": "^6.0.1",
-    "tsup": "^8.4.0",
-    "typescript": "^5.8.2",
-    "type-fest": "^4.37.0",
-    "vitest": "^2.1.9"
+    "@changesets/cli": "^2.29.8",
+    "@vitest/coverage-istanbul": "^4.0.16",
+    "rimraf": "^6.1.2",
+    "tsup": "^8.5.1",
+    "type-fest": "^5.3.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
   },
   "files": [
     "dist",
@@ -30,23 +30,27 @@
   "types": "./dist/types/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
     "./utils": {
+      "types": "./dist/utils.d.ts",
       "import": "./dist/utils.js",
       "require": "./dist/utils.cjs"
     }
   },
   "dependencies": {
-    "@auaust/primitive-kit": "^0.36.1"
+    "@auaust/primitive-kit": "^0.41.9"
   },
   "scripts": {
     "preinstall": "npx only-allow pnpm",
-    "build": "pnpm test && pnpm run build:clean && pnpm run build:js",
+    "build": "pnpm test && pnpm build:notest",
+    "build:notest": "pnpm run build:clean && pnpm run build:js",
     "build:clean": "rimraf dist",
     "build:js": "tsup",
     "test": "vitest run --config vitest.config.ts --typecheck -- && pnpm typecheck",
+    "test:dist": "pnpm build:notest && vitest run --config vitest.config.ts --typecheck --mode build --",
     "watch": "vitest --config vitest.config.ts --typecheck --",
     "coverage": "vitest run --coverage",
     "typecheck": "echo 'Typechecking...' && tsc --noEmit && echo 'All good!'",

package/src/classes/Color.ts

@@ -1,4 +1,4 @@
-import { N } from "@auaust/primitive-kit";
+import { isNumber } from "@auaust/primitive-kit/numbers";
 import type { Writable } from "type-fest";
 import type {
   ColorChannels,
@@ -6,14 +6,17 @@ import type {
   MaybeNamedColor,
   NamedColor,
   Rgb,
-} from "~";
+} from "~/index";
 import {
   brightness,
+  cache,
+  channels,
   closestNamedColor,
   contrast,
   distance,
   fallbackColor,
   grayscale,
+  invert,
   isAliasToNamedColor,
   isBright,
   isColor,
@@ -31,6 +34,7 @@ import {
   parseHex,
   parseNamedColor,
   parseRgb,
+  random,
   toAlphaChannel,
   toColorChannels,
   toHex,
@@ -38,8 +42,6 @@ import {
   toRgbChannel,
   type,
 } from "~/utils";
-import { random } from "~/utils/random";
-import { cache, channels } from "~/utils/symbols";
 
 export class Color {
   protected [channels]: Required<Writable<ColorChannels>> = undefined!;
@@ -52,31 +54,37 @@ export class Color {
   static from(value: ColorValue): Color;
   static from(red: number, green: number, blue: number, alpha?: number): Color;
   static from(value: ColorValue | number, ...rest: number[]): Color {
-    if (N.is(value)) {
-      return new this({ r: value, g: rest[0], b: rest[1], a: rest[2] });
+    if (isNumber(value)) {
+      return new Color({ r: value, g: rest[0], b: rest[1], a: rest[2] });
     }
 
-    return new this(parseColor(value ?? fallbackColor));
+    return new Color(parseColor(value ?? fallbackColor));
   }
 
   static fromChannels(channels: ColorChannels): Color {
-    return new this(channels);
+    return new Color(channels);
   }
 
   static fromRgb(rgb: Rgb): Color {
-    return new this(parseRgb(rgb));
+    return new Color(parseRgb(rgb));
   }
 
   static fromHex(hex: string): Color {
-    return new this(parseHex(hex));
+    return new Color(parseHex(hex));
   }
 
   static fromName(name: MaybeNamedColor): Color {
-    return new this(parseNamedColor(name));
+    return new Color(parseNamedColor(name));
+  }
+
+  static parse(value: ColorValue): ColorChannels | undefined {
+    const color = parseColor(value);
+
+    return color.isFallback ? undefined : color;
   }
 
   static random(presets: Parameters<typeof random>[0] = {}): Color {
-    return new this(random(presets));
+    return new Color(random(presets));
   }
 
   /**
@@ -324,12 +332,12 @@ export class Color {
 
   /** Returns the contrast ratio between this color and another. */
   contrast(color: ColorValue): number {
-    return contrast(this[channels], Color.from(color)[channels]);
+    return contrast(this[channels], parseColor(color));
   }
 
   /** Returns the distance between this color and another. If `alpha` is `true`, the alpha channel is included in the calculation. */
   distance(color: ColorValue, alpha = false): number {
-    return distance(this[channels], Color.from(color)[channels], alpha);
+    return distance(this[channels], parseColor(color), alpha);
   }
 
   /** Returns a new color with the grayscale equivalent of the current color, preserving the alpha channel. */
@@ -337,6 +345,10 @@ export class Color {
     return Color.fromChannels(grayscale(this[channels]));
   }
 
+  toInvert(): Color {
+    return Color.fromChannels(invert(this[channels]));
+  }
+
   toHex(): string {
     return this.memoize(toHex);
   }

package/src/data/fallbackColor.ts

@@ -0,0 +1,10 @@
+import type { ColorChannels } from "~/types";
+
+export const fallbackColor: Required<ColorChannels> = Object.freeze({
+  r: 0,
+  g: 0,
+  b: 0,
+  a: 1,
+  isTransformed: false,
+  isFallback: true,
+});

package/src/{utils → data}/namedColors.ts

@@ -1,13 +1,11 @@
-import { O, S } from "@auaust/primitive-kit";
-import type { ColorChannels, MaybeNamedColor, NamedColor } from "~/types";
-import { distance, fallbackColor, parseHex } from "~/utils";
+import type { NamedColor } from "~/types";
 
 /**
  * A map of named colors and their HEX values.
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/CSS/named-color
  */
-export const namedColorsMap = O.freeze({
+export const namedColorsMap = Object.freeze({
   aliceblue: "#f0f8ffff",
   antiquewhite: "#faebd7ff",
   aqua: "#00ffffff",
@@ -159,108 +157,6 @@ export const namedColorsMap = O.freeze({
   yellowgreen: "#9acd32ff",
 });
 
-const namedColors = new Set<NamedColor>(O.keys(namedColorsMap));
-
-const namedColorsChannelsCache: Partial<Record<NamedColor, ColorChannels>> = {};
-
-const namedColorsAliasesCache: Partial<
-  Record<NamedColor, readonly NamedColor[]>
-> = {};
-
-/**
- * Whether the input is a valid named color.
- *
- * The check is case-sensitive.
- */
-export function isNamedColor(value: unknown): value is NamedColor {
-  return S.is(value) && namedColors.has(<NamedColor>value.toLowerCase());
-}
-
-/**
- * Returns the color channels from a named color. Must be a valid named color, already lowercased.
- *
- * @internal
- */
-export function namedColorChannels(name: NamedColor): ColorChannels {
-  return (namedColorsChannelsCache[name] ??= parseHex(namedColorToHex(name)!));
-}
-
-/**
- * Returns the color channels from a named color.
- */
-export function parseNamedColor(name: MaybeNamedColor): ColorChannels {
-  if (!isNamedColor(name)) {
-    return fallbackColor;
-  }
-
-  return namedColorChannels(<NamedColor>name.toLowerCase());
-}
-
-/**
- * Returns the corresponding HEX value of a named color.
- */
-export function namedColorToHex(name: NamedColor): string;
-export function namedColorToHex(name: MaybeNamedColor): string | undefined;
-export function namedColorToHex(name: MaybeNamedColor): string | undefined {
-  return (
-    namedColorsMap[<keyof typeof namedColorsMap>name.toLowerCase()] || undefined
-  );
-}
-
-/** Returns the closest named color to the passed color channels. */
-export function closestNamedColor(channels: ColorChannels): NamedColor {
-  let closest: NamedColor | undefined;
-  let smallestDistance = Infinity;
-
-  for (const name of namedColors) {
-    const value = namedColorChannels(name);
-    const d = distance(
-      value,
-      channels,
-      value.a === 1 // Ignore alpha channel only if it's 1 -> allows to match transparent/black correctly
-    );
-
-    if (d < smallestDistance) {
-      closest = name;
-      smallestDistance = d;
-    }
-  }
-
-  return closest!;
-}
-
-/**
- * Returns all the aliases of a named color.
- */
-export function namedColorAliases(name: NamedColor): readonly NamedColor[] {
-  name = <NamedColor>name.toLowerCase();
-
-  if (!isNamedColor(name)) {
-    return [];
-  }
-
-  if (namedColorsAliasesCache[name]) {
-    return namedColorsAliasesCache[name]!;
-  }
-
-  const aliases: NamedColor[] = [];
-  const targetHex = namedColorToHex(name);
-
-  for (const [name, hex] of O.entries(namedColorsMap)) {
-    if (hex === targetHex) {
-      aliases.push(name);
-    }
-  }
-
-  return (namedColorsAliasesCache[name] = Object.freeze(aliases));
-}
-
-/**
- * Returns a boolean indicating whether two named colors are aliases.
- */
-export function isAliasToNamedColor(
-  name: NamedColor,
-  alias: NamedColor
-): boolean {
-  return namedColorAliases(name).includes(<NamedColor>alias.toLowerCase());
-}
+export const namedColors = new Set<NamedColor>(
+  Object.keys(namedColorsMap) as NamedColor[]
+);

package/src/types/index.ts

@@ -82,3 +82,5 @@ export type ColorChannels = {
    */
   readonly isFallback?: boolean;
 };
+
+export type ChannelRange = number | [min: number, max: number];

package/src/utils/brightness.ts

@@ -0,0 +1,17 @@
+import type { ColorChannels } from "~/types";
+import { luminance } from "~/utils";
+
+/**
+ * Returns the perceived brightness of a color normalized to the range [0, 1].
+ *
+ * @see https://stackoverflow.com/a/56678483
+ */
+export function brightness(channels: ColorChannels): number {
+  const l = luminance(channels);
+
+  if (l <= 216 / 24389) {
+    return (l * (24389 / 27)) / 100;
+  }
+
+  return (Math.pow(l, 1 / 3) * 116 - 16) / 100;
+}

package/src/utils/closestNamedColor.ts

@@ -0,0 +1,25 @@
+import type { ColorChannels, NamedColor } from "~/types";
+import { distance, namedColorChannels, namedColors } from "~/utils";
+
+/** Returns the closest named color to the passed color channels. */
+export function closestNamedColor(channels: ColorChannels): NamedColor {
+  let closest: NamedColor | undefined;
+  let smallestDistance = Infinity;
+
+  for (const name of namedColors) {
+    const value = namedColorChannels(name);
+
+    const d = distance(
+      value,
+      channels,
+      value.a === 1 // Ignore alpha channel only if it's 1 -> allows to match transparent/black correctly
+    );
+
+    if (d < smallestDistance) {
+      closest = name;
+      smallestDistance = d;
+    }
+  }
+
+  return closest!;
+}

package/src/utils/contrast.ts

@@ -0,0 +1,17 @@
+import { minMax } from "@auaust/primitive-kit/numbers";
+import type { ColorChannels } from "~/types";
+import { luminance } from "~/utils";
+
+/**
+ * Returns the contrast ratio between two colors.
+ *
+ * @see https://www.w3.org/TR/2008/REC-WCAG20-20081211/#contrast-ratiodef
+ */
+export function contrast(channelsA: ColorChannels, channelsB: ColorChannels) {
+  const [darkest, brightest] = minMax(
+    luminance(channelsA),
+    luminance(channelsB)
+  );
+
+  return (brightest + 0.05) / (darkest + 0.05);
+}

package/src/utils/couldBeRgb.ts

@@ -0,0 +1,13 @@
+import { isArray } from "@auaust/primitive-kit/arrays";
+import { isBetween, isNumber } from "@auaust/primitive-kit/numbers";
+import type { Rgb } from "~/types";
+
+/**
+ * Whether the input could be a valid RGB color.
+ * As in, it checks if the input is an array of numbers without validating the values range.
+ */
+export function couldBeRgb(value: unknown): value is Rgb {
+  return (
+    isArray(value) && isBetween(value.length, 3, 4) && value.every(isNumber)
+  );
+}

package/src/utils/grayscale.ts

@@ -0,0 +1,12 @@
+import type { ColorChannels } from "~/types";
+import { linearTosRGB, luminance, toColorChannels } from "~/utils";
+
+/**
+ * Returns the grayscale equivalent of a color as a new color channels object.
+ */
+export function grayscale(channels: ColorChannels): ColorChannels {
+  // Reverse gamma correction from luminance
+  const gray = linearTosRGB(luminance(channels)) * 255;
+
+  return toColorChannels(gray, gray, gray, channels.a);
+}

package/src/utils/index.ts

@@ -1,35 +1,46 @@
-export {
-  fallbackColor,
-  isAlphaChannel,
-  isColorChannels,
-  isRgbChannel,
-  toAlphaChannel,
-  toColorChannels,
-  toRgbChannel,
-} from "~/utils/channels";
-export { isColor, parseColor, type } from "~/utils/colors";
+import { cache, channels } from "~/utils/symbols";
+
+export { cache, channels }; // Not explicitly importing and exporting these symbols causes issues with TSUP when testing against the dist folder
+
+export { fallbackColor } from "~/data/fallbackColor";
+export { namedColors, namedColorsMap } from "~/data/namedColors";
+
+export { brightness } from "~/utils/brightness";
+export { closestNamedColor } from "~/utils/closestNamedColor";
+export { contrast } from "~/utils/contrast";
+export { couldBeRgb } from "~/utils/couldBeRgb";
 export { distance } from "~/utils/distance";
-export { isHex, parseHex, toHex } from "~/utils/hex";
-export {
-  brightness,
-  contrast,
-  grayscale,
-  isBright,
-  isDark,
-  linearTosRGB,
-  luminance,
-  sRGBtoLinear,
-} from "~/utils/luminance";
-export {
-  closestNamedColor,
-  isAliasToNamedColor,
-  isNamedColor,
-  namedColorAliases,
-  namedColorChannels,
-  namedColorsMap,
-  namedColorToHex,
-  parseNamedColor,
-} from "~/utils/namedColors";
-export { isOpaque, isTranslucent, isTransparent } from "~/utils/opacity";
-export { random, type ChannelRange } from "~/utils/random";
-export { couldBeRgb, isRgb, parseRgb, toRgb } from "~/utils/rgb";
+export { grayscale } from "~/utils/grayscale";
+export { invert } from "~/utils/invert";
+export { isAliasToNamedColor } from "~/utils/isAliasToNamedColor";
+export { isAlphaChannel } from "~/utils/isAlphaChannel";
+export { isBright } from "~/utils/isBright";
+export { isColor } from "~/utils/isColor";
+export { isColorChannels } from "~/utils/isColorChannels";
+export { isDark } from "~/utils/isDark";
+export { isHex } from "~/utils/isHex";
+export { isNamedColor } from "~/utils/isNamedColor";
+export { isOpaque } from "~/utils/isOpaque";
+export { isRgb } from "~/utils/isRgb";
+export { isRgbChannel } from "~/utils/isRgbChannel";
+export { isTranslucent } from "~/utils/isTranslucent";
+export { isTransparent } from "~/utils/isTransparent";
+export { linearTosRGB } from "~/utils/linearTosRGB";
+export { luminance } from "~/utils/luminance";
+export { namedColorAliases } from "~/utils/namedColorAliases";
+export { namedColorChannels } from "~/utils/namedColorChannels";
+export { namedColorToHex } from "~/utils/namedColorToHex";
+export { parseColor } from "~/utils/parseColor";
+export { parseHex } from "~/utils/parseHex";
+export { parseNamedColor } from "~/utils/parseNamedColor";
+export { parseRgb } from "~/utils/parseRgb";
+export { random } from "~/utils/random";
+export { randomAlphaChannel } from "~/utils/randomAlphaChannel";
+export { randomRgbChannel } from "~/utils/randomRgbChannel";
+export { sRGBtoLinear } from "~/utils/sRGBtoLinear";
+export { toAlphaChannel } from "~/utils/toAlphaChannel";
+export { toColorChannels } from "~/utils/toColorChannels";
+export { toHex } from "~/utils/toHex";
+export { toRgb } from "~/utils/toRgb";
+export { toRgbChannel } from "~/utils/toRgbChannel";
+export { type } from "~/utils/type";

package/src/utils/invert.ts

@@ -0,0 +1,11 @@
+import type { ColorChannels } from "~/types";
+import { toColorChannels } from "~/utils/toColorChannels";
+
+export function invert(channels: ColorChannels): ColorChannels {
+  return toColorChannels(
+    255 - channels.r,
+    255 - channels.g,
+    255 - channels.b,
+    channels.a
+  );
+}

package/src/utils/isAliasToNamedColor.ts

@@ -0,0 +1,12 @@
+import type { NamedColor } from "~/types";
+import { namedColorAliases } from "~/utils";
+
+/**
+ * Returns a boolean indicating whether two named colors are aliases.
+ */
+export function isAliasToNamedColor(
+  name: NamedColor,
+  alias: NamedColor
+): boolean {
+  return namedColorAliases(name).includes(<NamedColor>alias.toLowerCase());
+}

package/src/utils/isAlphaChannel.ts

@@ -0,0 +1,5 @@
+import { isBetween, isNumber } from "@auaust/primitive-kit/numbers";
+
+export function isAlphaChannel(value: unknown): value is number {
+  return isNumber(value) && isBetween(value, 0, 1);
+}

package/src/utils/isBright.ts

@@ -0,0 +1,7 @@
+import type { ColorChannels } from "~/types";
+import { brightness } from "~/utils";
+
+/** Returns whether the color is bright, as in its brightness is greater than 0.5 or the provided threshold. */
+export function isBright(channels: ColorChannels, threshold = 0.5): boolean {
+  return brightness(channels) > threshold;
+}

package/src/utils/isColor.ts

@@ -0,0 +1,7 @@
+import type { ColorValue } from "~/types";
+import { type } from "~/utils";
+
+/** Returns true if the value is any format of supported color. */
+export function isColor(value: unknown): value is ColorValue {
+  return type(value) !== undefined;
+}

package/src/utils/isColorChannels.ts

@@ -0,0 +1,13 @@
+import { isObject } from "@auaust/primitive-kit/objects";
+import type { ColorChannels } from "~/types";
+import { isAlphaChannel, isRgbChannel } from "~/utils";
+
+export function isColorChannels(value: unknown): value is ColorChannels {
+  return (
+    isObject(value, false) &&
+    isRgbChannel(value.r) &&
+    isRgbChannel(value.g) &&
+    isRgbChannel(value.b) &&
+    isAlphaChannel(value.a ?? 1)
+  );
+}

package/src/utils/isDark.ts

@@ -0,0 +1,7 @@
+import type { ColorChannels } from "~/types";
+import { brightness } from "~/utils";
+
+/** Returns whether the color is dark, as in its brightness is less than or equal to 0.5 or the provided threshold. */
+export function isDark(channels: ColorChannels, threshold = 0.5): boolean {
+  return brightness(channels) <= threshold;
+}

package/src/utils/isHex.ts

@@ -0,0 +1,27 @@
+import { isStrictString, isString } from "@auaust/primitive-kit/strings";
+import type { Hex } from "~/types";
+
+const hexadecimalRegex = /^[0-9A-Fa-f]+$/;
+
+/**
+ * Whether the input is a valid HEX color. With or without the alpha channel, and with single or double digits.
+ *
+ * It may or may not start with a hash character, which will be ignored.
+ */
+export function isHex(value: unknown): value is Hex {
+  value = isString(value) && (value.startsWith("#") ? value.slice(1) : value);
+
+  if (!isStrictString(value)) {
+    return false;
+  }
+
+  switch (value.length) {
+    case 3: // RGB
+    case 4: // RGBA
+    case 6: // RRGGBB
+    case 8: // RRGGBBAA
+      return hexadecimalRegex.test(value);
+    default:
+      return false;
+  }
+}

package/src/utils/isNamedColor.ts

@@ -0,0 +1,12 @@
+import { isString } from "@auaust/primitive-kit/strings";
+import { namedColors } from "~/data/namedColors";
+import type { NamedColor } from "~/types";
+
+/**
+ * Whether the input is a valid named color.
+ *
+ * The check is case-insensitive.
+ */
+export function isNamedColor(value: unknown): value is NamedColor {
+  return isString(value) && namedColors.has(<NamedColor>value.toLowerCase());
+}

package/src/utils/isOpaque.ts

@@ -0,0 +1,6 @@
+import type { ColorChannels } from "~/types";
+
+/** Checks if the color is fully opaque. */
+export function isOpaque(channels: ColorChannels) {
+  return channels.a === 1 || channels.a == undefined;
+}

package/src/utils/isRgb.ts

@@ -0,0 +1,15 @@
+import { isArray } from "@auaust/primitive-kit/arrays";
+import { isBetween } from "@auaust/primitive-kit/numbers";
+import type { Rgb } from "~/types";
+import { isAlphaChannel, isRgbChannel } from "~/utils";
+
+/**
+ * Whether the input is a valid RGB color.
+ */
+export function isRgb(value: unknown): value is Rgb {
+  return (
+    isArray(value) &&
+    isBetween(value.length, 3, 4) &&
+    value.every((n, i) => (i === 3 ? isAlphaChannel(n) : isRgbChannel(n)))
+  );
+}

package/src/utils/isRgbChannel.ts

@@ -0,0 +1,5 @@
+import { isBetween, isNumber } from "@auaust/primitive-kit/numbers";
+
+export function isRgbChannel(value: unknown): value is number {
+  return isNumber(value) && isBetween(value, 0, 255);
+}

package/src/utils/isTranslucent.ts

@@ -0,0 +1,7 @@
+import type { ColorChannels } from "~/types";
+import { isOpaque } from "~/utils";
+
+/** Checks if the color is at least partially transparent. */
+export function isTranslucent(channels: ColorChannels) {
+  return !isOpaque(channels);
+}

package/src/utils/isTransparent.ts

@@ -0,0 +1,6 @@
+import type { ColorChannels } from "~/types";
+
+/** Checks if the color is fully transparent. */
+export function isTransparent(channels: ColorChannels) {
+  return channels.a === 0;
+}

package/src/utils/linearTosRGB.ts

@@ -0,0 +1,10 @@
+/**
+ * Returns the gamma corrected sRGB value of a linear channel.
+ */
+export function linearTosRGB(channel: number) {
+  if (channel <= 0.04045 / 12.92) {
+    return channel * 12.92;
+  }
+
+  return 1.055 * Math.pow(channel, 1 / 2.4) - 0.055;
+}