@auaust/jaune 0.0.3 → 0.0.5

package/src/utils/luminance.ts

@@ -1,32 +1,5 @@
-import { N } from "@auaust/primitive-kit";
 import type { ColorChannels } from "~/types";
-import { toColorChannels } from "./channels";
-
-/**
- * Returns the linearized value of a sRGB channel.
- *
- * @see https://stackoverflow.com/a/56678483
- */
-export function sRGBtoLinear(channel: number) {
-  if (channel <= 0.04045) {
-    return channel / 12.92;
-  }
-
-  return Math.pow((channel + 0.055) / 1.055, 2.4);
-}
-
-/**
- * Returns the gamma corrected sRGB value of a linear channel.
- *
- * @see sRGBtoLinear
- */
-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;
-}
+import { sRGBtoLinear } from "~/utils";
 
 /**
  * Returns the luminance of a color normalized to the range [0, 1].
@@ -41,52 +14,3 @@ export function luminance(channels: ColorChannels) {
 
   return r * 0.2126 + g * 0.7152 + b * 0.0722;
 }
-
-/**
- * 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;
-}
-
-/** 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;
-}
-
-/** 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;
-}
-
-/**
- * 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] = N.minMax(
-    luminance(channelsA),
-    luminance(channelsB)
-  );
-
-  return (brightest + 0.05) / (darkest + 0.05);
-}
-
-/**
- * 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/namedColorAliases.ts

@@ -0,0 +1,33 @@
+import { entries } from "@auaust/primitive-kit/objects";
+import type { NamedColor } from "~/types";
+import { isNamedColor, namedColorToHex, namedColorsMap } from "~/utils";
+
+const namedColorsAliasesCache: Partial<
+  Record<NamedColor, readonly NamedColor[]>
+> = {};
+
+/**
+ * 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 entries(namedColorsMap)) {
+    if (hex === targetHex) {
+      aliases.push(name);
+    }
+  }
+
+  return (namedColorsAliasesCache[name] = Object.freeze(aliases));
+}

package/src/utils/namedColorChannels.ts

@@ -0,0 +1,13 @@
+import type { ColorChannels, NamedColor } from "~/types";
+import { namedColorToHex, parseHex } from "~/utils";
+
+const namedColorsChannelsCache: Partial<Record<NamedColor, ColorChannels>> = {};
+
+/**
+ * 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)!));
+}

package/src/utils/namedColorToHex.ts

@@ -0,0 +1,11 @@
+import { namedColorsMap } from "~/data/namedColors";
+import type { MaybeNamedColor, NamedColor } from "~/types";
+
+/**
+ * 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[<NamedColor>name.toLowerCase()] || undefined;
+}

package/src/utils/parseColor.ts

@@ -0,0 +1,44 @@
+import { Color } from "~/classes/Color";
+import type { ColorChannels } from "~/types";
+import {
+  channels,
+  couldBeRgb,
+  fallbackColor,
+  isColorChannels,
+  isHex,
+  isNamedColor,
+  parseHex,
+  parseNamedColor,
+  parseRgb,
+} from "~/utils";
+
+/** Tries to parse the value as a color. If it fails, returns the fallback color. */
+export function parseColor(value: unknown): ColorChannels {
+  if (!value) {
+    return fallbackColor;
+  }
+
+  if (value instanceof Color) {
+    return value[channels];
+  }
+
+  if (isColorChannels(value)) {
+    return value;
+  }
+
+  if (isNamedColor(value)) {
+    return parseNamedColor(value);
+  }
+
+  if (isHex(value)) {
+    return parseHex(value);
+  }
+
+  if (couldBeRgb(value)) {
+    // It might not be a valid RGB, in which case `parseRgb` is responsible for returning the fallback color
+    // In case more color types are added, it might be required to only return the result of `parseRgb` if `isFallback` is false
+    return parseRgb(value);
+  }
+
+  return fallbackColor;
+}

package/src/utils/parseHex.ts

@@ -0,0 +1,23 @@
+import type { ColorChannels, Hex } from "~/types";
+import { toColorChannels } from "~/utils";
+
+/**
+ * Parses a hex string into an object of color channels.
+ *
+ * The input must already be a valid HEX color, otherwise the result will be unexpected.
+ */
+export function parseHex(value: Hex): ColorChannels {
+  value = value.startsWith("#") ? value.slice(1) : value;
+
+  const isShort = value.length < 6;
+  const hasAlpha = isShort ? value.length === 4 : value.length === 8;
+
+  const r = parseInt(isShort ? value[0].repeat(2) : value.slice(0, 2), 16);
+  const g = parseInt(isShort ? value[1].repeat(2) : value.slice(2, 4), 16);
+  const b = parseInt(isShort ? value[2].repeat(2) : value.slice(4, 6), 16);
+  const a = hasAlpha
+    ? parseInt(isShort ? value[3].repeat(2) : value.slice(6, 8), 16) / 255
+    : 1;
+
+  return toColorChannels(r, g, b, a);
+}

package/src/utils/parseNamedColor.ts

@@ -0,0 +1,13 @@
+import type { ColorChannels, MaybeNamedColor, NamedColor } from "~/types";
+import { fallbackColor, isNamedColor, namedColorChannels } from "~/utils";
+
+/**
+ * Returns the color channels from a named color.
+ */
+export function parseNamedColor(name: MaybeNamedColor): ColorChannels {
+  if (!isNamedColor(name)) {
+    return fallbackColor;
+  }
+
+  return namedColorChannels(<NamedColor>name.toLowerCase());
+}

package/src/utils/parseRgb.ts

@@ -0,0 +1,14 @@
+import { isArray } from "@auaust/primitive-kit/arrays";
+import type { ColorChannels, Rgb } from "~/types";
+import { fallbackColor, toColorChannels } from "~/utils";
+
+/**
+ * Parses a RGB tuple into an object of color channels.
+ *
+ * The input must already be a valid RGB tuple, otherwise the result will be unexpected.
+ */
+export function parseRgb(value: Rgb): ColorChannels {
+  return isArray(value)
+    ? toColorChannels(value[0], value[1], value[2], value[3]) // Don't spread to avoid mistakenly forwarding `isTransformed` and `isFallback`
+    : fallbackColor;
+}

package/src/utils/random.ts

@@ -1,32 +1,5 @@
-import { A, N } from "@auaust/primitive-kit";
-import type { ColorChannels } from "~/types";
-import { toColorChannels } from "~/utils";
-
-export type ChannelRange = number | [min: number, max: number];
-
-function randomRgbChannel(range?: ChannelRange | undefined): number {
-  if (N.is(range)) {
-    return range;
-  }
-
-  if (A.is(range)) {
-    return N.randInt(range[0], range[1]);
-  }
-
-  return N.randInt(0, 255);
-}
-
-function randomAlphaChannel(range?: ChannelRange | undefined): number {
-  if (N.is(range)) {
-    return range;
-  }
-
-  if (A.is(range)) {
-    return N.randFloat(range[0], range[1]);
-  }
-
-  return 1;
-}
+import type { ChannelRange, ColorChannels } from "~/types";
+import { randomAlphaChannel, randomRgbChannel, toColorChannels } from "~/utils";
 
 /**
  * Generates a random color.

package/src/utils/randomAlphaChannel.ts

@@ -0,0 +1,15 @@
+import { isArray } from "@auaust/primitive-kit/arrays";
+import { isNumber, randomFloat } from "@auaust/primitive-kit/numbers";
+import type { ChannelRange } from "~/types";
+
+export function randomAlphaChannel(range?: ChannelRange | undefined): number {
+  if (isNumber(range)) {
+    return range;
+  }
+
+  if (isArray(range)) {
+    return randomFloat(range[0], range[1]);
+  }
+
+  return 1;
+}

package/src/utils/randomRgbChannel.ts

@@ -0,0 +1,15 @@
+import { isArray } from "@auaust/primitive-kit/arrays";
+import { isNumber, randomInteger } from "@auaust/primitive-kit/numbers";
+import type { ChannelRange } from "~/types";
+
+export function randomRgbChannel(range?: ChannelRange | undefined): number {
+  if (isNumber(range)) {
+    return range;
+  }
+
+  if (isArray(range)) {
+    return randomInteger(range[0], range[1]);
+  }
+
+  return randomInteger(0, 255);
+}

package/src/utils/sRGBtoLinear.ts

@@ -0,0 +1,12 @@
+/**
+ * Returns the linearized value of a sRGB channel.
+ *
+ * @see https://stackoverflow.com/a/56678483
+ */
+export function sRGBtoLinear(channel: number) {
+  if (channel <= 0.04045) {
+    return channel / 12.92;
+  }
+
+  return Math.pow((channel + 0.055) / 1.055, 2.4);
+}

package/src/utils/toAlphaChannel.ts

@@ -0,0 +1,5 @@
+import { clamp, isNumber } from "@auaust/primitive-kit/numbers";
+
+export function toAlphaChannel(value: number | undefined | null): number {
+  return isNumber(value) ? clamp(value, 0, 1) : 1;
+}

package/src/utils/{channels.ts → toColorChannels.ts}

@@ -1,31 +1,6 @@
-import { N, O } from "@auaust/primitive-kit";
+import { isObject } from "@auaust/primitive-kit/objects";
 import type { ColorChannels } from "~/types";
-
-export function isRgbChannel(value: unknown): value is number {
-  return N.is(value) && N.isBetween(value, 0, 255);
-}
-
-export function toRgbChannel(value: number | undefined | null): number {
-  return N.clamp(N.round(value), 0, 255);
-}
-
-export function isAlphaChannel(value: unknown): value is number {
-  return N.is(value) && N.isBetween(value, 0, 1);
-}
-
-export function toAlphaChannel(value: number | undefined | null): number {
-  return N.is(value) ? N.clamp(value, 0, 1) : 1;
-}
-
-export function isColorChannels(value: unknown): value is ColorChannels {
-  return (
-    O.is(value, false) &&
-    isRgbChannel(value.r) &&
-    isRgbChannel(value.g) &&
-    isRgbChannel(value.b) &&
-    isAlphaChannel(value.a ?? 1)
-  );
-}
+import { fallbackColor, toAlphaChannel, toRgbChannel } from "~/utils";
 
 /**
  * Formats the input into a readonly object of color channels.
@@ -51,7 +26,7 @@ export function toColorChannels(
   isTransformed?: boolean,
   isFallback?: boolean
 ): Required<ColorChannels> {
-  if (O.is(r, false)) {
+  if (isObject(r, false)) {
     ({ r, g, b, a, isTransformed, isFallback } = r);
   }
 
@@ -65,7 +40,7 @@ export function toColorChannels(
 
   const finalA = toAlphaChannel(a);
 
-  return O.freeze({
+  return Object.freeze({
     r: finalR,
     g: finalG,
     b: finalB,
@@ -80,5 +55,3 @@ export function toColorChannels(
     isFallback: !!isFallback,
   });
 }
-
-export const fallbackColor = toColorChannels(0, 0, 0, 1, false, true);

package/src/utils/toHex.ts

@@ -0,0 +1,29 @@
+import { isNumber, max, round } from "@auaust/primitive-kit/numbers";
+import type { ColorChannels, Hex } from "~/types";
+import { toRgbChannel } from "~/utils";
+
+/**
+ * Returns the corresponding hex string of a color channels object.
+ *
+ * If the alpha channel is 1, it will be omitted.
+ */
+export function toHex(channels: ColorChannels): Hex {
+  const { r, g, b, a } = channels;
+
+  return (
+    "#" +
+    (
+      (1 << 24) +
+      (toRgbChannel(r) << 16) +
+      (toRgbChannel(g) << 8) +
+      toRgbChannel(b)
+    )
+      .toString(16)
+      .substring(1) +
+    (isNumber(a) && a < 1
+      ? round(max(0, a) * 255)
+          .toString(16)
+          .padStart(2, "0")
+      : "")
+  );
+}

package/src/utils/toRgb.ts

@@ -0,0 +1,13 @@
+import type { ColorChannels, Rgb } from "~/types";
+import { toAlphaChannel, toRgbChannel } from "~/utils";
+
+/**
+ * Returns the corresponding RGB tuple of a color channels object.
+ */
+export function toRgb(channels: ColorChannels): Rgb {
+  const { r, g, b, a } = channels;
+
+  return Array.from([r, g, b, a], (value, i) =>
+    i === 3 ? toAlphaChannel(value) : toRgbChannel(value)
+  );
+}

package/src/utils/toRgbChannel.ts

@@ -0,0 +1,5 @@
+import { clamp, round } from "@auaust/primitive-kit/numbers";
+
+export function toRgbChannel(value: number | undefined | null): number {
+  return clamp(round(value), 0, 255);
+}

package/src/utils/type.ts

@@ -0,0 +1,32 @@
+import { Color } from "~/classes/Color";
+import type { ColorType } from "~/types";
+import { isColorChannels, isHex, isNamedColor, isRgb } from "~/utils";
+
+/** Returns the color type of the value, or undefined if it's not a color. */
+export function type(value: unknown): ColorType | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  if (value instanceof Color) {
+    return "color";
+  }
+
+  if (isNamedColor(value)) {
+    return "named";
+  }
+
+  if (isHex(value)) {
+    return "hex";
+  }
+
+  if (isRgb(value)) {
+    return "rgb";
+  }
+
+  if (isColorChannels(value)) {
+    return "channels";
+  }
+
+  return undefined;
+}

package/src/utils/colors.ts

@@ -1,72 +0,0 @@
-import { Color } from "~/classes/Color";
-import type { ColorChannels, ColorType, ColorValue } from "~/types";
-import { fallbackColor, isColorChannels } from "./channels";
-import { isHex, parseHex } from "./hex";
-import { isNamedColor, parseNamedColor } from "./namedColors";
-import { couldBeRgb, isRgb, parseRgb } from "./rgb";
-import { channels } from "./symbols";
-
-/** Returns true if the value is any format of supported color. */
-export function isColor(value: unknown): value is ColorValue {
-  return type(value) !== undefined;
-}
-
-/** Returns the color type of the value, or undefined if it's not a color. */
-export function type(value: unknown): ColorType | undefined {
-  if (!value) {
-    return undefined;
-  }
-
-  if (value instanceof Color) {
-    return "color";
-  }
-
-  if (isNamedColor(value)) {
-    return "named";
-  }
-
-  if (isHex(value)) {
-    return "hex";
-  }
-
-  if (isRgb(value)) {
-    return "rgb";
-  }
-
-  if (isColorChannels(value)) {
-    return "channels";
-  }
-
-  return undefined;
-}
-
-/** Tries to parse the value as a color. If it fails, returns the fallback color. */
-export function parseColor(value: unknown): ColorChannels {
-  if (!value) {
-    return fallbackColor;
-  }
-
-  if (value instanceof Color) {
-    return value[channels];
-  }
-
-  if (isColorChannels(value)) {
-    return value;
-  }
-
-  if (isNamedColor(value)) {
-    return parseNamedColor(value);
-  }
-
-  if (isHex(value)) {
-    return parseHex(value);
-  }
-
-  if (couldBeRgb(value)) {
-    // It might not be a valid RGB, in which case `parseRgb` is responsible for returning the fallback color
-    // In case more color types are added, it might be required to only return the result of `parseRgb` if `isFallback` is false
-    return parseRgb(value);
-  }
-
-  return fallbackColor;
-}

package/src/utils/hex.ts

@@ -1,75 +0,0 @@
-import { N, S } from "@auaust/primitive-kit";
-import type { ColorChannels, Hex } from "~/types";
-import { toColorChannels, toRgbChannel } from "./channels";
-
-const hexadecimalRegex = /^[0-9a-f]+$/i;
-
-/**
- * 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 = S.is(value) && (value.startsWith("#") ? value.slice(1) : value);
-
-  if (!S.isStrict(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;
-  }
-}
-
-/**
- * Parses a hex string into an object of color channels.
- *
- * The input must already be a valid HEX color, otherwise the result will be unexpected.
- */
-export function parseHex(value: Hex): ColorChannels {
-  value = value.startsWith("#") ? value.slice(1) : value;
-
-  const isShort = value.length < 6;
-  const hasAlpha = isShort ? value.length === 4 : value.length === 8;
-
-  const r = parseInt(isShort ? value[0].repeat(2) : value.slice(0, 2), 16);
-  const g = parseInt(isShort ? value[1].repeat(2) : value.slice(2, 4), 16);
-  const b = parseInt(isShort ? value[2].repeat(2) : value.slice(4, 6), 16);
-  const a = hasAlpha
-    ? parseInt(isShort ? value[3].repeat(2) : value.slice(6, 8), 16) / 255
-    : 1;
-
-  return toColorChannels(r, g, b, a);
-}
-
-/**
- * Returns the corresponding hex string of a color channels object.
- *
- * If the alpha channel is 1, it will be omitted.
- */
-export function toHex(channels: ColorChannels): Hex {
-  const { r, g, b, a } = channels;
-
-  return (
-    "#" +
-    (
-      (1 << 24) +
-      (toRgbChannel(r) << 16) +
-      (toRgbChannel(g) << 8) +
-      toRgbChannel(b)
-    )
-      .toString(16)
-      .substring(1) +
-    (N.is(a) && a < 1
-      ? N.round(N.max(0, a) * 255)
-          .toString(16)
-          .padStart(2, "0")
-      : "")
-  );
-}

package/src/utils/opacity.ts

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